Skip to main content

(Step 2) [POST] Create a Remote Payment

Description​

Once you have the Device to which you want to send a Payment, initiate a Remote Payment by follow the instructions below.

This API supports optional callback_url and callback_token fields. If provided by you, the system will deliver asynchronous notifications (callbacks) to that URL when the payment state changes.

⚠️ Note: callback_url and callback_token are currentky available only available in the staging environment. (See the Environments section).

Requirements​

  • A Location must exist (each payment is related to a location_id). The location is liked to the API KEY you have been given to access our SYstems.
  • A valid device_id (obtained from the Devices API).

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 Payments​

{
  "remote_payment": {
    "external_reference": string,
    "amount": "number($double)",
    "description": "string", [*optional]
    "payment_type": [ bank, crypto, card ], (enum)
    "metadata": {"string"}, [*optional] (JSON format)
    "device_id": "integer",
    "callback_url": string [*optional],
    "callback_token": string [*optional]
  }
}

Below you have a short description of each field:

  • 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 Payment.
  • amount, is the payment amount we want to start with the Remote Payment.
  • description, is the description of the payment, it is an optional field.
  • payment_type, may be of the type card, crypto or bank, depending on the type of payment you want to initiate.
    • Please note only card is currently available.
  • metadata, it is an optional field, here you can save whatever you want.
  • device_id, is the terminal number to which you want to send the payment, by doing the GET devices (previous step) you have obtained it.
  • callback_url, The URL used to deliver the remote payment response. This field is optional. If provided, changes of status related to refund, cancelation, and abort will be automatically notified on this URL.
  • callback_token, The token used to authenticate the remote payment response. This field is optional. It will be included in the automatic response once the payment is approved, refused, canceled. etc

Note: The fields callback_url and callback_token are only available in the staging environment.

Environments​

Staging environment​

POST https://staging.sylq.io/remote_api/v1/remote_payments

Production/Live environment​

POST https://app.sylq.io/remote_api/v1/remote_payments

Example of Request to Create a Remote Payment​

As a "Header" we need to specify the "Authorization" (Bearer value) and a Body JSON:

{
  "remote_payment": {
    "external_reference": "123456",
    "amount": 10,
    "currency": "EUR",
    "description": "Example of description",
    "payment_type": "card",
    "metadata": {"value":"Example of value"},
    "device_id": 1,
    "callback_url": "https://your.endpoint/receive",
    "callback_token": "your secret-token-123"
  }
}

Examples of returns​

Success response (200)​

{
  "success": true,
  "message": "Success",
  "data": {
    "id": 31,
    "external_reference": "123456",
    "device_id": 1,
    "place_id": 1,
    "created_at": "2024-01-03T08:59:48.169Z",
    "payment": {
      "id": 3477,
      "reference": "P0DTCZKFBY",
      "description": "Example of description",
      "amount": 10.0,
      "currency": "EUR",
      "status": "pending",
      "type": "card",
      "latitude": null,
      "longitude": null,
      "merchant_id": 2661
    }
  }
}

Error responses​

Unauthorized (401)​

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

{
  "message": "Unauthorized"
}

Unprocessable Entity (422)​

This error appears when we have initiated a card type payment but our associated Merchant does not have a contract to initiate card payments. It can also happen with crypto or bank.

{
    "success": false,
    "message": "Unprocessable Entity"
}