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:

{
"txId": "76d1c6e1-d580-4017-84a7-92128769d874",
"apiResponseStatus": {
"responseCode": "I07000",
"httpStatus": "CREATED",
"message": "OK"
}
}

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:

{
"txId": "503232a9-00b9-4d63-b939-d9ac0a58a72a",
"cart": "f4edc86a-8e97-4be0-8354-29c018975e37",
"currency": "EUR",
"amount": 10000,
"method": "CASH",
"settlement": "79b2c009-ab57-4d22-ade4-3ef416dd2f3f"
}

These are some important attributes to keep in mind when making the request:

  • The previously created txId value needed to process payment.
  • ThecartId 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:

{
"remainder": 0,
"change": -2000,
"txId": "503232a9-00b9-4d63-b939-d9ac0a58a72a",
"currency": "EUR",
"paymentStatus": "CLOSED",
"apiResponseStatus": {
"responseCode": "I07000",
"httpStatus": "CREATED",
"message": "OK"
}
}

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:

{
"remainder": 2000,
"change": 0,
"txId": "503232a9-00b9-4d63-b939-d9ac0a58a72a",
"currency": "EUR",
"paymentStatus": "PARTIAL",
"apiResponseStatus": {
"responseCode": "I07000",
"httpStatus": "CREATED",
"message": "OK"
}
}

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:

{
"txId": "98520022-7cec-4017-af3d-0dfbe5d8a3f0",
"cart": "f4edc86a-8e97-4be0-8354-29c018975e37",
"currency": "EUR",
"amount": 0,
"method": "CASH",
"settlement": "79b2c009-ab57-4d22-ade4-3ef416dd2f3f"
}

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.
  • Thesettlement value the payment is related to.

Example response:

{
"remainder": 0,
"change": 8000,
"txId": "98520022-7cec-4017-af3d-0dfbe5d8a3f0",
"currency": "EUR",
"paymentStatus": "CLOSED",
"apiResponseStatus": {
"responseCode": "I07000",
"httpStatus": "CREATED",
"message": "OK"
}
}

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.