Payment API
Introduction
The payment API provide endpoints to make payments and refund for carts. There are different payment methods and currencies supported.
For more details about this API usage check our API documentation
Preparation
- Have an authenticated token from the authentication service, this token should be used as an authorization
bearer token
header for every request done in this API (more information about the authorization service here). - Have the cart ID you wish to make payment for (more information about carts here).
- An active (OPEN) settlement to which payment will be related to (more information about settlements here).
Generate a transaction Id
To effectively make a payment (or refund) we first need to generate a transaction Id (txId
), for this, we simply need
to make a GET request to the endpoint payments/tx
. The value given in the response will be unique and is to uniquely
identify each payment request made. There is no request body to be sent.
Example response:
In the response we expect to get the txId
which need to be reused in the endpoints to perform payments or refunds.
Make a payment
After having generated a transaction Id we can proceed to make payment for an existing cart by making a POST request to
the payments/payment
endpoint. Here is an example request for a CASH payment of a cart worth 80,00€.
Example request:
These are some important attributes to keep in mind when making the request:
- The previously created
txId
value needed to process payment. - The
cartId
for which the payment will be made for. amount
is the money to be paid. The value units are represented in cents (10000 represents 100,00€).- The value of an active (OPEN)
settlement
value the payment is related to.
Example response:
Here are some important observations in the response:
remainder
represents the amount of currency left to be paid for the cart Id provided in the request. In this example, the cart was paid entirely. This value is also represented in cents.change
represents the money given back to the customer as change when a payment exceeds the remainder amount to be paid. In this example, the cart price was of 8000 (80,00€), since the payment done was 10000 the change given back to the customer is 2000. This value is also represented in cents.paymentStatus
tells us if there are still payments left to be done related to the cart Id provided, a CLOSED status means that all payments related to the cart are done and no further payments should be processed.
There is also a different response when a cart is not entirely paid, which indicates us to make further payments to completely pay it.
Example response:
Here are some important observations in the response:
- In this example the cart was not paid entirely, the
remainder
amount to be paid is 2000. - The
paymentStatus
is PARTIAL, it means the cart has been partially paid, this value indicates us to make further payments to complete the payment process of the cart.
Make a refund
After having created a payment the user have a possibility to make a refund for all, or some items previously
purchased in a cart. For this, a return cart should be previously created, the amount to be refunded to the customer
will be calculated in the refund cart as a negative value (more information about refund carts here). To perform a
refund payment we need also need to generate transaction Id and make a POST request to the payments/payment
endpoint.
The cart id of a refund cart needs to be provided in the request body. Here is an example request for a refund payment
made in CASH for a cart worth -80,00€.
Example request:
These are some important attributes to keep in mind when making the request:
- The
cartId
of the refund cart. - The
amount
value for processing a refund payment should be 0 since the total price of a refund cart is a negative value. - The
method
specifies the payment method the refund will be given back to the customer, have in mind that not all payment methods are eligible to perform refund payments. - The
settlement
value the payment is related to.
Example response:
Here are some important observations in the response:
- The
remainder
value is the amount of money left to be refunded to the customer, the value is always 0 since refunds are always done in a single refund payment request. - The
change
represents the amount of money refunded back to the customer. paymentStatus
tells us if there are still payments left to be done related to the cart Id provided, a CLOSED status means that all payments related to the cart are done and no further payments should be processed.