Skip to main content

[POST] Create a Remote Payment Refund by Payment Reference

Description​

Once we have the Payment confirmed, the only thing left to do is to start the Refund. To do this, you will have to follow the steps indicated here.

Requirements​

ℹ️ Before launching a payment or refund, you need to have a Location created, as each payment will be related to a Location (location_id).

Authentication​

In all your requests you need to add, as a Header, your Authorization Token-ID:

"Name": "Authorization"
"Value": "Bearer YOUR-TOKEN-ID"

Schema for Remote Payment Refunds​

{
  "amount": 0,
  "currency": "EUR",
  "notes": "string",
  "refund_method": "card",
  "device_id": 0,
  "external_reference": "string"
}

Below you have a short description of each field:

  • amount, is the refund amount we want to start with the Refund Payment.
  • notes, is the description of the refund, it is an optional field.
  • currency, is the currency associated to the payment, EUR by default.
  • refund_method, if the type of the refund card, crypto or bank. Currently, is only available the card option.
  • device_id, is the terminal number to which you want to send the payment, by doing the GET devices (please, visit GET Devices if you want more information) you have obtained it.
  • external_reference, is a field where you will send the external reference, for example from your accounting system, cash register, etc... with this number you can then retrieve the status of the Refund.

Environments​

Staging environment​

POST https://staging.sylq.io/remote_api/v1/remote_payments/{payment_reference}/refunds

Production/Live environment​

POST https://app.sylq.io/remote_api/v1/remote_payments/{payment_reference}/refunds

Example of Request to Create a Refund Remote Payment​

As a "Header" we need to specify the "Authorization" (Bearer value), as a request parameter you have the payment_reference which in the example you can see corresponds to Payment with Reference 3NVHIQG33L and a Body JSON. See an example:

curl -i -H "Accept: application/json" -H "Authorization: Bearer YOUR-TOKEN-ID" -X GET "https://staging.sylq.io/remote_api/v1/remote_payments/3NVHIQG33L/refunds"

Body Request:

{
  "amount": 0,
  "currency": "EUR",
  "notes": "string",
  "refund_method": "card",
  "device_id": 0,
  "external_reference": "string"
}

Examples of returns​

Success response (200)​

{
  "success": true,
  "message": "Success",
  "data": {
    "id": 106,
    "payment_refund_id": 96,
    "refund_method": "card",
    "amount_refunded": "0.0",
    "amount_refundable": "0.0",
    "amount": "1.0",
    "currency": "EUR",
    "type": "total",
    "refund_reference": "3CGHV3PH3U",
    "payment_reference": "LCEODE3Y9L",
    "external_reference": "ABC1234",
    "notes": null,
    "status": "new",
    "device": {
      "id": 174,
      "name": "PAX A50",
      "os_system": "Android 8.1.0",
      "sylq_app_version": "3.1.9",
      "place_id": 19,
      "created_at": "2024-02-05T14:43:29.221Z"
    },
    "created_at": "2024-02-06T15:43:41.398Z"
  }
}

Error responses​

Unauthorized (401)​

This error appears it is because the credential (Authorization) is incorrect or does not exist.

{
  "message": "Unauthorized"
}

Device Not Found (404)​

This error appears, it is because an incorrect device_id has been specified in the call or cannot be found.

{
  "success": false,
  "message": "Record not found"
}

Unprocessable entity response (422)​

This error appears when the amount indicated for the refund is greater than the amount of the payment to be refunded.

{
  "success": false,
  "message": "The amount of the refund cannot be greater than the amount of the payment to be refunded"
}