Skip to main content

(Step 2) [POST] Create a Remote Payment

Description​

Once we have the Device to which we want to send the Payment, the only thing left to do is to initiate the Payment. To do so, you will have to follow the steps indicated here.

Requirements​

ℹ️ Before launching a payment, 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 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"
  }
}

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.
  • 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.

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
  }
}

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"
}