Skip to main content
Version: 1.0.0

KubePay API Documentation

This document is intended as a guide to help anyone who wants to integrate a KubePay payment system into their platform.

Before being able to process payments, you must pass a certification and development process. If you have not done so already, please contact us at the following email address: partner@kubepay.io. We will provide you with a test account and guide you through the process.



Payment gateway: Getting started​

You can integrate payments with KubePay on any platform, this payment solution is not subject to any specific programming language or framework, so you can integrate payments with KubePay using React, Angular, Vue, or even with vanilla javascript.

KubePay provides a number of endpoints to send and receive information about the payment and the status of the transaction. As a partner, you can make use of these endpoints to show users different screens, texts or images depending on the payment status.



Payment flow​

Pay Button​

You can design your own button to pay with KubePay, depending on the design of your website and your other payment methods, you may want to design a button with square corners or rounded edges, you can also choose to add the KubePay logo inside the button, or just make a button with the text "Pay with KubePay", integrate the design according to your needs!

Init transaction​

Once the user has selected KubePay as the payment method (generally by clicking the button), you must obtain a unique id to identify the transaction that is trying to be performed (from now on called intent_id).

To obtain this intent_id, you must make a call to the /create endpoint indicating the transaction data in the request body (amount, currency, etc.)

(Note: you will normally call the /create endpoint from your backend so that you can handle the transaction information internally, but if you don't need to do any internal operations, you can also call this endpoint directly from your frontend)

Retrieve transaction data​

When you have obtained the intent_id of the transaction, make a first call to the endpoint

/api/gateway/payments/{intentId}/public/

This endpoint will return useful information about the transaction, such as the total amount, the status of the transaction (pending, partial payment, payment completed, time expired, etc..), which you can use to show the user different content depending on that data.

As payments are not made immediately, we recommend making a call to the endpoint at regular time intervals (min every 3 seconds, recommended every 10 seconds) in order to get the most up-to-date information.

Transaction data​

You can check all the transaction data received from the endpoint here.

Below is detailed how to use some of transaction data to update the user interface.

  • expires_at: the specific time in which the transaction expires, you can use this time to show the user the indicated date or to display a countdown timer.
  • pay_address: the address to which the payment should be made, you can use this information to directly display the address, to generate a QR code, or offer the user both options.
  • total_amount: the total amount of the transaction, you can use it to update the payment details in the UI.
  • partial_amount: the amount that has already been received in the event that the amount sent does not reach the total, it is useful when the user makes the payment in two or more fractions. With this data you can show the user how much money has been received and how much remains to be received.
  • status: the status of the transaction, can be one of the following: paid, pending, partial, failed, expired. Use the transaction status to update the UI depending on the status, for example, you can display an animation and text while the status received is pending, and when the received status change to paid, send the user to the "Payment made successfully" screen.

Payment confirmation​

Once the full payment has been received through the KubePay platform, you have two options to receive the payment confirmation:

  • Use a webhook: In the KubePay administration panel, introduce the url that you want to be called when the payment is confirmed (in progress).

  • Use the transaction status: You can use the status property of the transaction data in order to know when a transaction has been completed, once you receive paid as the transaction status, you can execute a function in your code that calls your own endpoint to get the payment confirmation.

Authentication​

Security Scheme Type:http
HTTP Authorization Scheme:bearer
Bearer format:JWT