Skip to main content
Paylands documentation
Paylands API Reference
Documentation Powered by ReDoc

Paylands documentation (1.0.0)

Download OpenAPI specification:Download

Got any questions? Contact us here: soporte@paylands.com

Authentication

When using the API you will need to authenticate your API calls with your API Key in every request. Your API Key implies many privileges, so make sure to keep it secret. Do not share your API Key nor expose it to the client or within a public website.

API authentication is based on HTTP Basic Auth. API Key must be sent as the value for the username field. It is not necessary to send any value for the password field. If this header is set manually, API Key must be base64 encoded.

In case you need to authenticate using bearer auth (as a cross-origin request, for example), include the modifier -H "Authorization: Bearer " instead of -u :.

All API calls must be performed under HTTPS. HTTP requests and unauthenticated calls will be denied.

Request authentication

API Request authentication example.

header Parameters
Authorization
required
string
Example: Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=

Authorization header containing your API key.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "message": "OK",
  • "current_time": "2019-05-30T12:55:48+0200"
}

API Keys

View my API key profiles

This endpoint returns the profiles of the API key that was used in the request. If the API key has total access, it will return all.

header Parameters
Authorization
required
string
Example: Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=

Authorization header containing your API key.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "current_time": "2019-05-30T12:55:48+0200",
  • "message": "OK",
  • "profiles": [
    ]
}

View the profiles of my API key

This endpoint returns all the profiles that an API key can have.

  • all: Full access
  • payment: Order creation, payment, refunds, confirmation and cancellation, card tokenization
  • refund: Refunding orders.
  • readonly: Reading orders, customers, cards, etc
  • card: Tokenizing, listing, modifying and deleting cards
  • tokenize: Card tokenization
  • moto: Uploading MoTo campaigns
  • batch_authorization: Uploading batches of payments
  • batch_refund: Uploading batches of refunds
  • keyentry: Processing manual payments
header Parameters
Authorization
required
string
Example: Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=

Authorization header containing your API key.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "current_time": "2019-05-30T12:55:48+0200",
  • "message": "OK",
  • "profiles": [
    ]
}

Payments

Payment order

This endpoint generates a payment order. It does not make the payment, just initializes all required parameters for a future payment.

header Parameters
Authorization
required
string
Example: Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=

Authorization header containing your API key.

Request Body schema: application/json
signature
required
string

Signature paired with the API key. Required in all POST/PUT/DELETE requests.

amount
required
number >= 0

Amount to charge, in the fractional currency of your choice. An amount of 100 using the currency EUR is equal to 1€.

operative
required
string
Enum: "AUTHORIZATION" "DEFERRED" "PAYOUT" "TRANSFER"

Operative to be used during the payment.

secure
required
boolean

true if the payment will require 3D Secure. Otherwise false.

customer_ext_id
string

External ID provided by the merchant to uniquely identify a customer.

service
string

The UUID of the payment service used to perform the operation.

currency
string Nullable

Alpha 3 ISO 4217 code of the currency. Mandatory if service is not provided.

description
required
string

Payment description. This field is what users will see on their bank statement in bank transfer transactions.

additional
string

Free field provided by the merchant. May be used to store any kind of data.

url_post
string

URL that will receive an HTTP notification containing the payment's outcome.

url_ok
string

URL to which the customer will be redirected after the payment if they were successfully charged.

url_ko
string

URL to which the customer will be redirected after the payment if they could not be charged.

template_uuid
string

Payment card template shown to the customer during the payment process. If the value is null, the default payment card template will be used instead.

dcc_template_uuid
string Nullable

DCC template shown to the customer during the payment process. If the value is null, the default DCC template will be used instead.

source_uuid
string

Unique identifier of the payment method used to perform the payment.

save_card
boolean
Default: true

Whether or not the user has given consent for their card to be stored for future payments. The card may be used regardless of the value of this field. It is the merchant who must take into account the value of this field.

reference
string Nullable

The reference of the order. May be used as an external identifier or to avoid duplicate payments.

dynamic_descriptor
string Nullable

Dynamic descriptor of the payment on the customer's bank account. May not match this exact value.

expires_in
number [ 600 .. 31536000 ] Nullable
Default: 600

Time in seconds since the order is created until it expires.

object (ExtraData)

Responses

Request samples

Content type
application/json
{
  • "signature": "341f7de8e6fc49da8d8736473af6b03a",
  • "amount": 100,
  • "operative": "AUTHORIZATION",
  • "secure": true,
  • "customer_ext_id": "test",
  • "service": "9A1BDCC8-DB30-4ED2-8523-62B330A67873",
  • "currency": "EUR",
  • "description": "Payment #1",
  • "additional": null,
  • "url_post": "https://my.website.com/process",
  • "url_ok": "https://my.website.com/ok",
  • "url_ko": "https://my.website.com/ko",
  • "template_uuid": "6412549E-933E-4DFE-A225-2E87FBF7623E",
  • "dcc_template_uuid": "BF418CA6-7043-4864-B36F-F02C2CF2B76B",
  • "source_uuid": null,
  • "save_card": true,
  • "reference": "50620",
  • "dynamic_descriptor": "PNP*NombreComercio",
  • "expires_in": 3600,
  • "extra_data": {
    }
}

Response samples

Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2021-12-28T15:29:49+0100",
  • "order": {
    },
  • "client": {
    },
  • "extra_data": {
    },
  • "validation_hash": "5fb245ebd2bea93d38212c7cd9a74ad18cdbc4036cc674d225bead28fc784f90"
}

Send payment order link by SMS/Mail

This endpoint sends the payment link by SMS or email to the destination.

header Parameters
Authorization
required
string
Example: Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=

Authorization header containing your API key.

Request Body schema: application/json
signature
required
string

Signature paired with the API key. Required in all POST/PUT/DELETE requests.

order_uuid
required
string

Unique identifier of the order.

destination
required
string

The email address or mobile number to which the payment order is to be sent.

subject
required
string

Message title.

template_uuid
string Nullable

Template shown to the customer on the payment notification when type is "EMAIL" or "SMS". If the value is null, the default template will be used instead.

language
string

The language used during the payment process in ISO 639-1 format.

Responses

Request samples

Content type
application/json
{
  • "signature": "341f7de8e6fc49da8d8736473af6b03a",
  • "order_uuid": "1F405EA3-9798-42A6-9E87-BD347EF67F55",
  • "destination": "name@example.com",
  • "subject": "Título del mensaje",
  • "template_uuid": "6412549E-933E-4DFE-A225-2E87FBF7623E",
  • "language": "es"
}

Response samples

Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2021-12-28T13:51:27+0100",
  • "delivery": true
}

Single-step payment

This endpoint generates a payment order, stores the card and executes the payment on a single request. It is only usable if you are PCI compliant.

If the payment is not secure, the order will be paid through a direct payment. In case the antifraud detects risk, a link will be returned in order for the customer to finalize the tokenized payment through 3D Secure. Otherwise the payment will finalize as usual.

If the payment is secure, a link will be returned in order for the customer to finalize the tokenized payment through 3D Secure.

header Parameters
Authorization
required
string
Example: Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=

Authorization header containing your API key.

Request Body schema: application/json
signature
required
string

Signature paired with the API key. Required in all POST/PUT/DELETE requests.

amount
required
number >= 0

Amount to charge, in the fractional currency of your choice. An amount of 100 using the currency EUR is equal to 1€.

operative
required
string
Enum: "AUTHORIZATION" "DEFERRED" "PAYOUT" "TRANSFER"

Operative to be used during the payment.

secure
required
boolean

true if the payment will require 3D Secure. Otherwise false.

customer_ext_id
required
string

External ID provided by the merchant to uniquely identify a customer.

service
required
string

The UUID of the payment service used to perform the operation.

description
required
string

Payment description. This field is what users will see on their bank statement in bank transfer transactions.

additional
string

Free field provided by the merchant. May be used to store any kind of data.

url_post
string

URL that will receive an HTTP notification containing the payment's outcome.

url_ok
string

URL to which the customer will be redirected after the payment if they were successfully charged.

url_ko
string

URL to which the customer will be redirected after the payment if they could not be charged.

template_uuid
string

Payment card template shown to the customer during the payment process. If the value is null, the default payment card template will be used instead.

dcc_template_uuid
string Nullable

DCC template shown to the customer during the payment process. If the value is null, the default DCC template will be used instead.

card_holder
required
string

Cardholder name.

card_pan
required
string

Primary account number (PAN).

card_expiry_month
required
string

Expiry month of the card.

card_expire_year
string

Expiry year of the card.

card_additional
string

Free field provided by the merchant. May be used to store any kind of data.

card_cvv
string

Card Verification Value (CVV) usually displayed on the back of the card.

customer_ip
string

IP of the user.

reference
string Nullable

The reference of the order. May be used as an external identifier or to avoid duplicate payments.

dynamic_descriptor
string Nullable

Dynamic descriptor of the payment on the customer's bank account. May not match this exact value.

expires_in
number [ 600 .. 31536000 ] Nullable
Default: 600

Time in seconds since the order is created until it expires.

object Nullable

Field containing the information from the merchant if you have indicated authentication via External MPI/3DS.

object (ExtraData)

Responses

Request samples

Content type
application/json
{
  • "signature": "341f7de8e6fc49da8d8736473af6b03a",
  • "amount": 100,
  • "operative": "AUTHORIZATION",
  • "secure": false,
  • "customer_ext_id": "test",
  • "service": "9A1BDCC8-DB30-4ED2-8523-62B330A67873",
  • "description": "Payment #1",
  • "additional": null,
  • "url_post": "https://my.website.com/process",
  • "url_ok": "https://my.website.com/ok",
  • "url_ko": "https://my.website.com/ko",
  • "template_uuid": "6412549E-933E-4DFE-A225-2E87FBF7623E",
  • "dcc_template_uuid": "BF418CA6-7043-4864-B36F-F02C2CF2B76B",
  • "card_holder": "Jose",
  • "card_pan": "4761739000060016",
  • "card_expiry_month": "12",
  • "card_expiry_year": "21",
  • "card_additional": "Card additional",
  • "card_cvv": "123",
  • "customer_ip": "127.0.0.1",
  • "reference": "50620",
  • "dynamic_descriptor": "PNP*NombreComercio",
  • "threeds_data": {
    },
  • "expires_in": 3600
}

Response samples

Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2021-12-28T13:24:26+0100",
  • "order": {
    },
  • "client": {
    },
  • "validation_hash": "88e0b4e4ca902beb6df70693a0a94164be0485bab865dc168e3a1bf6bf5a71f7"
}

Bizum

The user is redirected to the Bizum payment page, where they must enter the phone number of the account from which they wish to pay.

This payment method is only available in REDSYS and it will be necessary to activate it previously: contact support to activate this configuration.

In SANDBOX environment, successful and refused payments can be simulated by entering the following values when the payment process asks for the phone number:

  • Successful payment: 700000000
  • Refused payment: ko@ko.ko
path Parameters
token
required
string
Example: ebc9b5ffa2efcf74197734a071192817e6f2a3fc15f49c4b1bdb6edc46b16e3ab4109498bff8e6ba00fb6d2bd1838afbea67095c4caaa2f46e4acf4d5851884c

The token of the order.

Responses

Response samples

Content type
text/html
Cancellation 
This endpoint frees the balance being held by a DEFERRED operative.
 
If a cancellation attempt fails, you must wait 1 minute from the last unsuccessful attempt before making a new attempt. In case of a successful cancellation, it is not necessary to wait for another cancellation attempt. However, if the system detects 3 failed attempts in total, no further attempts will be allowed until the start of the next day.
 
From the third unsuccessful attempt onwards, only one unsuccessful cancellation will be allowed per day. This means that after the first three failed retries, if the next one also fails, you will have to wait until the next day to make another attempt.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
order_uuid
 required 
string
 
Unique identifier of the order.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "order_uuid": "1f405ea3-9798-42a6-9e87-bd347ef67f55"
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2021-12-28T13:00:42+0100",
  • "order": {
    },
  • "client": {
    },
  • "validation_hash": "e9e97e6514c2a2e2367207c4f39c25e6feb852788c412ec9814fa2a49c7cad57"
}
Confirmation 
This endpoint charges the balance being held by a DEFERRED operative.
 
If a confirmation attempt fails, it shall wait 1 minute from the last failed attempt before making a new attempt. In the event of a successful confirmation, it shall not be necessary to wait for another confirmation attempt. However, if the system detects 3 failed attempts in total, no further attempts will be allowed until the start of the next day.
 
From the third unsuccessful attempt onwards, only one unsuccessful confirmation will be allowed per day. This means that after the first three failed retries, if the next one also fails, you will have to wait until the next day to make another attempt.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
order_uuid
 required 
string
 
Unique identifier of the order.
 
amount
number
 
Amount to capture. If not provided, all remaining amount will be captured. Can be provided only if partial captures are supported.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "order_uuid": "1f405ea3-9798-42a6-9e87-bd347ef67f55",
  • "amount": 100
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2021-12-28T13:06:17+0100",
  • "order": {
    },
  • "client": {
    },
  • "validation_hash": "b34f457d184499c182f2066337aef97e568a6813fd50b0d23a9af88c921cb4d0"
}
WebService 
User intervention is not required when using this method. It will be necessary to provide the payment order UUID and the card's UUID which will have ben previously stored.
 
If antifraud system is enabled, some rules could be triggered and it would be necessary user authentication (3DS) to finish the payment. In this case, response will contain the URL the user must be redirected to in order to authenticate himself and complete the payment.
 
This URL must not be changed under any circumstances, as its syntax may change on future releases. It should only be retrieved from response's body and used to redirect the user.
 
The IP address of the customer that is about to pay must be included in IPv4 or IPv6 format. Otherwise, antifraud measures related to the customer's IP won't be executed.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
order_uuid
 required 
string
 
Unique identifier of the order.
 
card_uuid
 required 
string
 
Unique identifier of the card.
 
customer_ip
string
 
IP of the user.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "order_uuid": "1F405EA3-9798-42A6-9E87-BD347EF67F55",
  • "card_uuid": "C10721E7-1404-45DC-8762-351DD9945D1D",
  • "customer_ip": "62.43.214.55"
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2021-12-28T13:51:27+0100",
  • "order": {
    },
  • "client": {
    },
  • "validation_hash": "88e0b4e4ca902beb6df70693a0a94164be0485bab865dc168e3a1bf6bf5a71f7"
}
MoTo payment via API 
This method allows you to pay for an order with the payment data obtained by mail or telephone. This operation will not require authentication, as it is a PSD2-exempt operation. It is only usable if you are PCI compliant.
 
If anti-fraud is activated, orders considered risky will be processed without any additional restrictions.
 
To carry out this payment it will be necessary to indicate the card to be used. There are two ways to do this: indicating the card data separately (card_holder, card_pan, card_expire_month, card_expire_year, and optionally with card_cvv and card_additional) or, if the card is already tokenized, indicating its uuid in the source_uuid field only.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
order_uuid
 required 
string
 
Unique identifier of the order.
 
method
 required 
string
 Enum: "MAIL" "PHONE" 
 
Origin of the card details (phone call or through mail).
 
card_holder
string
 
Cardholder name.
 
card_pan
string
 
Primary account number (PAN).
 
card_expiry_month
string
 
Expiry month of the card.
 
card_expiry_year
string
 
Expiry year of the card.
 
card_cvv
string
 
Card Verification Value (CVV) usually displayed on the back of the card.
 
card_additional
string
 
Description that will be assigned to the card.
 
source_uuid
string
 
Unique identifier of the payment method used to perform the payment.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "order_uuid": "1f405ea3-9798-42a6-9e87-bd347ef67f55",
  • "method": "MAIL",
  • "card_holder": "John Doe",
  • "card_pan": "4111111111111111",
  • "card_expiry_month": "12",
  • "card_expiry_year": "19",
  • "card_cvv": "123",
  • "card_additional": "card12345"
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2021-12-28T15:39:48+0100",
  • "order": {
    },
  • "client": {
    },
  • "validation_hash": "32e999af0254635606ef70d1cb7b8148c0182c1b75c85a73af27cb676563882d"
}
Redirection 
This method allows the user to be redirected to a payment screen where they will be prompted for their payment method, which can be a card or an APM (alternative payment method). The requested token is the one that is returned when generating a payment order.
 
Alternatively, if the UUID of a checkout has been indicated at the time of generating the payment order, this method will redirect the user to the checkout to select which payment method they want to use to pay, and will be guided until the payment process is completed.
 
path Parameters
token
 required 
string
 
 Example:  ebc9b5ffa2efcf74197734a071192817e6f2a3fc15f49c4b1bdb6edc46b16e3ab4109498bff8e6ba00fb6d2bd1838afbea67095c4caaa2f46e4acf4d5851884c
The token of the order.
 
query Parameters
apm
string
 Enum: "BIZUM" "IDEAL" "SOFORT" "KLARNA" "VIACASH" "COFIDIS" "PIX" "CRYPTO" "GIROPAY" "TRANSFER" "PSE" "PAYPAL" "PAYLATER" "SPEI" "MULTIBANCO" "MBWAY" "FLOA" "PAYSAFECARD" "PAGO_FACIL" "EFECTY" "BOLETO" "LOTERICA" "PAYSHOP" "PICPAY" "MACH" "KLAP" "KHIPU" "SERVIPAG" 
 
 Example:  apm=BIZUM
Name of the APM (alternative payment method) to which the user will be redirected. Required when the service provided when generating the payment order supports multiple APMs. Should not be provided when the payment will be made by card.
 
Responses
 Response samples 
Content type
text/html
Refund 
Using this endpoint, a refund into the source card is requested. If the amount field is not sent, it will be a full refund. Otherwise, the refund will be requested for the specified amount (in case it''s valid).
 
When the refund is made by a marketplace. The extra_data field must be included, indicating within marketplace_refunds and the data pertinent to each merchant and the amount refunded by each one.
 
In the amount field, of the merchant that makes the refund, will be equal to the amount indicated outside of the extra_data and the net_amount will indicate the amount that will be refunded by each of the parties involved in the refund.
 
If a refund attempt fails, you must wait 1 minute from the last unsuccessful attempt before making a new attempt. In the event of a successful refund, it will not be necessary to wait for another refund attempt to be made. However, if the system detects 3 failed attempts in total, no further attempts will be allowed until the start of the next day.
 
From the third unsuccessful attempt onwards, only one unsuccessful return will be allowed per day. This means that after the first three failed retries, if the next one also fails, you will have to wait until the next day to make another attempt.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
order_uuid
 required 
string
 
Unique identifier of the order.
 
amount
number  >= 0  Nullable 
 
Amount to refund, in the fractional currency of your choice. An amount of 100 using the currency EUR is equal to 1€.
 
object Nullable 
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "order_uuid": "1f405ea3-9798-42a6-9e87-bd347ef67f55",
  • "amount": 100,
  • "extra_data": {
    }
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2021-12-28T15:53:55+0100",
  • "order": {
    },
  • "client": {
    },
  • "validation_hash": "63d795ea1cf9c77d7d9a4c52e6c174b97ffed8292d163fe2a92c268c6fd3f3b1"
}
Tokenized using 3DS 
This method is similar to webservice payment, but in this case, the 3DS screen will be shown to the user before completing the payment.
 
path Parameters
token
 required 
string
 
 Example:  ebc9b5ffa2efcf74197734a071192817e6f2a3fc15f49c4b1bdb6edc46b16e3ab4109498bff8e6ba00fb6d2bd1838afbea67095c4caaa2f46e4acf4d5851884c
The token of the order.
 
Responses
 Response samples 
Content type
text/html
PUSH payment 
This method allows initiating alternative payments without the user having to be present during the process in front of a web browser. In some payment methods such as Bizum, the call to this method will send the PUSH notification to the user's cell phone to carry out the payment. In others, it will return the information necessary for the payment to be carried out.
 
If a payment service supports more than one APM (alternative payment method), the APM to be used must be indicated in the body of the request.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
order_uuid
 required 
string
 
Unique identifier of the order.
 
apm
string
 Enum: "BIZUM" "IDEAL" "SOFORT" "KLARNA" "VIACASH" "COFIDIS" "PIX" "CRYPTO" "GIROPAY" "TRANSFER" "PSE" "PAYPAL" "PAYLATER" "SPEI" "MULTIBANCO" "MBWAY" "FLOA" "PAYSAFECARD" "PAGO_FACIL" "EFECTY" "BOLETO" "LOTERICA" "PAYSHOP" "PICPAY" "MACH" "KLAP" "KHIPU" "SERVIPAG" 
 
Alternative payment method.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "order_uuid": "1f405ea3-9798-42a6-9e87-bd347ef67f55",
  • "apm": "BIZUM"
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2021-12-28T15:39:48+0100",
  • "order": {
    },
  • "client": {
    },
  • "extra_data": {
    },
  • "validation_hash": "32e999af0254635606ef70d1cb7b8148c0182c1b75c85a73af27cb676563882d"
}
Payment by wallet 
If you want to directly integrate Google Pay or Apple Pay, you can proceed with the payment indicating the order to pay and the Payload returned by any of these wallets. This flow is necessary in payments through an APP since it is not possible to show the Google Pay or Apple Pay button in a webview from a mobile device.
 
If the wallet is Google Pay, it may be necessary to finalize the payment through 3DS. In this case, the response will contain the URL to which the user must be redirected to authenticate and complete the payment. If the wallet is Apple Pay, the order will be considered 3DS because Apple Pay is considered a secure payment method.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
order_uuid
 required 
string
 
Unique identifier of the order.
 
wallet
 required 
string
 Enum: "GOOGLEPAY" "APPLEPAY" 
 
Type of wallet used.
 
payload
 required 
string
 
Payload returned by the wallet (Google Pay or Apple Pay).
 
customer_ip
string
 
IP of the user.
 
flow
string Nullable 
 Default:  "APP"
 Enum: "APP" "WEB" 
 
Indicates whether the card was obtained through the browser or a mobile app.
 
Responses
 Request samples 
Content type
application/json
Example
Google pay payload example
Google pay payload example
Apple pay payload example
{
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "order_uuid": "1F405EA3-9798-42A6-9E87-BD347EF67F55",
  • "wallet": "GOOGLEPAY",
  • "payload": {
    },
  • "customer_ip": "62.43.214.55",
  • "flow": "WEB"
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2021-12-28T13:51:27+0100",
  • "order": {
    },
  • "client": {
    },
  • "validation_hash": "88e0b4e4ca902beb6df70693a0a94164be0485bab865dc168e3a1bf6bf5a71f7"
}
Payouts
Payout 
Transfers funds to the specified source_uuid of the customer. To send money to a card, it is necessary for the card to have carried out a previous payment in the terminal. If source_uuid is not provided, the last card that has made a successful payment and is associated with the customer_ext_id indicated when generating the order will be selected.
 
There are also other ways to transfer funds to a customer. Some services support alternative payment methods such as Bizum, PIX or bank transfers. If a service with more than one way of transferring funds such as Redsys is used, it is mandatory to provide the apm field to specify which one will be used. You can find more information about these payment methods in the Documentation. Not all APM support payouts.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
order_uuid
 required 
string
 
Unique identifier of the order.
 
source_uuid
string
 
Unique identifier of the payment method used to perform the payment.
 
customer_ip
string
 
IP of the user.
 
apm
string
 Enum: "BIZUM" "IDEAL" "SOFORT" "KLARNA" "VIACASH" "COFIDIS" "PIX" "CRYPTO" "GIROPAY" "TRANSFER" "PSE" "PAYPAL" "PAYLATER" "SPEI" "MULTIBANCO" "MBWAY" "FLOA" "PAYSAFECARD" "PAGO_FACIL" "EFECTY" "BOLETO" "LOTERICA" "PAYSHOP" "PICPAY" "MACH" "KLAP" "KHIPU" "SERVIPAG" 
 
Alternative payment method.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "order_uuid": "1f405ea3-9798-42a6-9e87-bd347ef67f55",
  • "source_uuid": "C10721E7-1404-45DC-8762-351DD9945D1D",
  • "customer_ip": "127.0.0.1",
  • "apm": "BIZUM"
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2021-12-28T16:08:07+0100",
  • "order": {
    },
  • "client": {
    },
  • "validation_hash": "81c46c70ab2ec6f766b0e118cd7fe8e39641aee9bee8c7a67dcf87b9a4c3ddc0"
}
Orders
Expire order 
This endpoint allows you to expire a payment order. Once expired, the payment link can no longer be used.
 
path Parameters
order_uuid
 required 
string
 
 Example:  1F405EA3-9798-42A6-9E87-BD347EF67F55
Unique identifier of the order.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b"
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2021-12-29T10:14:14+0100"
}
Get order 
This endpoint returns all the information about an order, including its current status and transactions. If the transaction was processed using a physical device, a "pos" field will appear including its details
 
path Parameters
order_uuid
 required 
string
 
 Example:  1f405ea3-9798-42a6-9e87-bd347ef67f55
Unique identifier of the order.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Responses
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2021-12-17T11:46:00+0100",
  • "order": {
    },
  • "client": {
    },
  • "validation_hash": "69fa69f2e333e5199357a33bb06d048495c86ca38ba822e4aa4c38405f6648c0"
}
Get all orders 
This endpoint returns all the client (and children) transactions, based on several filters included in the queryString.
 
query Parameters
start
string
 
 Example:  start=202012312359
Initial date in YYYYMMDDHHmm format.
 
end
string
 
 Example:  end=202112312359
Final date in YYYYMMDDHHmm format.
 
updated_at_start
string
 
 Example:  updated_at_start=202012312359
Initial updated_at date of the transaction in YYYYMMDDHHmm format.
 
updated_at_end
string
 
 Example:  updated_at_end=202112312359
Final updated_at date of the transaction in YYYYMMDDHHmm format.
 
terminal
number
 
 Example:  terminal=65432781
The terminal's code (FUC). Redsys only.
 
limit
number
 
 Example:  limit=10
Max result count of the query. By default and as an upper limit, 10000.
 
offset
number
 
 Example:  offset=20
Number of results to skip. May be used to paginate the results.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Responses
 Response samples 
Content type
application/json
{
  • "code": 200,
  • "count": 2,
  • "current_time": "2017-01-01T00:00:00+0200",
  • "message": "OK",
  • "transactions": [
    ]
}
Transactions
Bind metadata to a transaction 
Endpoint to associate metadata to a transaction. Up to 20 key-value pairs can be associated with the transaction, which will be included later when exporting transactions through Paylands.
 
path Parameters
transaction_uuid
 required 
string
 
 Example:  1F405EA3-9798-42A6-9E87-BD347EF67F55
Unique identifier of the transaction.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
metadata
 required 
array
 
Array of key-value pairs that will be associated as metadata to the transaction. A maximum of 20 pairs can be included.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "metadata": {
    }
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2021-12-29T10:14:14+0100"
}
Merchants
Paylands offers the possibility of creating merchants via API for those merchants that are partners.
 
Create 
Using this method, we can create a new business under the customer indicated in parent_uuid. If parent_uuid is not included or set to null, the merchant will be created by default under the client to which the credentials belong.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
name
 required 
string
 
Name of the merchant.
 
email
 required 
string
 
Email.
 
timezone
 required 
boolean
 
Merchant timezone.
 
autorecover_transactions
boolean
 
Automatically retrieve pending transactions.
 
resend_failed_notifications
boolean
 
Set to true to forward requests to the merchant that have not returned a 200 to Paylands.
 
category
string
 Enum: "ACCOUNTING_SERVICES" "ADULT" "ALCOHOL" "CBD" "CELL_PHONE_SALES" "CHARITY" "COMPUTING_AND_HARDWARE" "COMPUTING_SERVICES" "CROWDFUNDING" "CROWDLENDING" "CRYPTO" "CURRICULUMS" "DATING_AND_SCORT_SERVICES" "E_COMMERCE" "ELECTRONIC_CIGARETTE" "EVENTS_SALES" "FOREX_WITH_LICENSE" "FOREX_WITHOUT_LICENSE" "GAMBLING_WITH_LICENSE" "GAMBLING_WITHOUT_LICENSE" "GAMING" "HOSTING_SERVICES" "HOTELS" "JEWELRY" "LEGAL_SERVICES" "MARKETPLACE" "MOBILE_RECHARGE" "MONEY_REMMITANCE" "NUTRITION" "PAYDAY_LOANS" "TOBACCO" "TOUR_OPERATOR_OTAS" "VOUCHERS" "WALLETS" 
 
Category merchant.
 
mcc
string  4 characters 
 
Merchant Category Code, must contain four numbers.
 
parent_uuid
string Nullable 
 
Indicates the parent of the merchant if you want to create it under another client than the one making the request.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "name": "Client Name",
  • "email": "email@email.com",
  • "timezone": "Europe/Madrid",
  • "autorecover_trasactions": false,
  • "resend_failed_notifications": false,
  • "category": "HOTELS",
  • "mcc": "5732",
  • "parent_uuid": "8dc780e8-c311-4791-a47f-c1a272ffbb87"
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2017-01-12T09:12:58+0100",
  • "client": {
    }
}
Promote 
This endpoint is used to promote a merchant, which only exists in sandbox environment, to the production environment.
 
path Parameters
uuid
 required 
string
 
 Example:  1F405EA3-9798-42A6-9E87-BD347EF67F55
Client's UUID
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b"
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2024-01-12T09:12:58+0100",
  • "uuid": "962C3723-A0BC-4911-8F0F-0CCE963C5218",
  • "api_key": "17CFBB43E7D4417BB532370C2C5B499F",
  • "signature": "21c49b786c21b89k06782mjv1a40bc21"
}
Create a dashboard user 
By using this endpoint, you can create a dashboard user with access to visualize merchant's transactions.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
email
 required 
string
 
Email of the customer.
 
username
 required 
string
 
User's name.
 
language
 required 
string
 Enum: "ES" "EN" "PT" 
 
User's default language that will be used when accessing the control panel
 
environment
 required 
string
 Enum: "SANDBOX" "PRODUCTION" 
 
User's default environment.
 
send_email_with_credentials
 required 
boolean
 
Whether an email containing login details must be sent or not
 
group
 required 
string
 Enum: "MANAGER" "USER" "VIEWER" "MANUAL PAYMENT" "BATCH" "PAYMENTS" 
 
     
  • MANAGER: has access to all sections, including reporting and configuration ones
    •  
  • USER: has access to transactions, terminals and payment services
    •  
  • VIEWER: can visualize transactions and MoTo payments
    •  
  • MANUAL PAYMENT: can execute manual payments and visualize transactions
    •  
  • BATCH: can process and list batch payments
    •  
  • PAYMENTS: has access to all transactions and cards list (no sensitive data is exposed)
    •  
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "email": "email@email.com",
  • "username": "John",
  • "language": "ES",
  • "environment": "SANDBOX",
  • "send_email_with_credentials": false,
  • "group": "MANAGER"
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2017-01-12T09:12:58+0100",
  • "user": {
    },
  • "password": "Tpdle7ew7Y",
  • "email": "johndoe@test.com"
}
List a client's services 
This method returns the list of payment services associated with a specific customer.
 
path Parameters
client_uuid
 required 
string
 
 Example:  c52c2f9e-8ae9-4599-8e64-fcabd38d8e71
Client UUID.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Responses
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2024-05-21T14:52:09+0200",
  • "services": [
    ]
}
Services
Paylands offers the possibility of creating services via API for those merchants that are partners.
 
Create 
Using this method, we can create a new service. If a terminal is not indicated, the service will remain pending.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
name
 required 
string
 
Service name.
 
type
 required 
string
 Enum: "EVOSNAP" "MIT" "CREDIBANCOECOMMERCE" "REDSYSPSD2" "CLEARHAUS" "TRUSTPAYMENTS" "CREDORAX" "DLOCAL" "CECABANK" "NIUBIZ" "CYBERSOURCE" "VIACASH" "SAFETYPAY" "NUVEI" "FACILITAPAY" "COFIDIS" "PAYLANDS" "WORLDPAY" "DECTA" "DEVENGO" "INESPAY" "WALLETTO" "PAYPAL" "PAYMENTSWAY" "FLOA" "BKN301" "SILVERFLOW" "CHECKOUT" "EUPAGO" "PAGSMILE" "SIBS" "PAYSHOP" 
 
Service type.
 
dcc_mode
string
 Enum: "LOCAL" "FOREIGN" "DYNAMIC" 
 
DCC that was configured on the merchant account.
 
is_dcc_allowed
boolean
 
Allows dcc. Only applies to REDSYS services..
 
terminal_uuid
string
 
Terminal associated with the service.
 
parent_uuid
string
 
This UUID belongs to the merchant that will own the service.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "name": "Service name",
  • "type": "REDSYSPSD2",
  • "dcc_mode": "LOCAL",
  • "is_dcc_allowed": false,
  • "terminal_uuid": null,
  • "parent_uuid": null
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2017-01-12T09:12:58+0100",
  • "service": {
    }
}
Terminals
Create 
Terminal creation requires a few common fields for all terminal types, but also specific fields depending on the terminal provider. On the right side, the "Request Samples" section contains a dropdown including the specific fields that must be sent for different providers.
 
In case you need to register a terminal type not showing there, please send an email to soporte@paylands.com so we can include it.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
currency_code
 required 
string
 
Currency's alpha3 code. For example: EUR.
 
type
 required 
string
 Enum: "EVOSNAP" "MIT" "CREDIBANCOECOMMERCE" "REDSYSPSD2" "CLEARHAUS" "TRUSTPAYMENTS" "CREDORAX" "DLOCAL" "CECABANK" "NIUBIZ" "CYBERSOURCE" "VIACASH" "SAFETYPAY" "NUVEI" "FACILITAPAY" "COFIDIS" "PAYLANDS" "WORLDPAY" "DECTA" "DEVENGO" "INESPAY" "WALLETTO" "PAYPAL" "PAYMENTSWAY" "FLOA" "BKN301" "SILVERFLOW" "CHECKOUT" "EUPAGO" "PAGSMILE" "SIBS" "PAYSHOP" 
 
Service type.
 
description
 required 
string
 
Short text associated to the terminal
 
code
string
 
Numeric code associated to virtual mids. For example, for Redsys' terminals it would be the FUC code.
 
parent_uuid
string
 
This UUID belongs to the merchant that will own the terminal.
 
Responses
 Request samples 
Content type
application/json
Example
Create a Redsys terminal
Create a Redsys terminal
Create a Shift4/Finaro terminal
{
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "description": "Sandbox terminal for merchant1234",
  • "type": "REDSYSPSD2",
  • "currency_code": "EUR",
  • "code": "341111111",
  • "key_secure": "c421c8j2h490x2783hdnd93k1q",
  • "key_not_secure": "54f23c8v74528949b4mjjk3s",
  • "terminal_secure": "1",
  • "terminal_not_secure": "2",
  • "parent_uuid": null
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2017-01-12T09:12:58+0100",
  • "terminal": {
    }
}
Customers
Create 
This method creates a new customer, which will be used later to associate a tokenized card.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
customer_ext_id
 required 
string
 
External ID provided by the merchant to uniquely identify a customer.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "customer_ext_id": "customer15487"
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2017-01-12T09:12:58+0100",
  • "Customer": {
    }
}
Create account 
This method creates the data associated with a user's bank account in the system.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
external_id
 required 
string
 
External ID provided by the merchant to uniquely identify a customer.
 
account_type
 required 
string (AccountType) 
 Enum: "ACCOUNT_NUMBER" "BUSINESS" "ACCOUNT_CLABE" "CARD_NUMBER" "INTEREST_CHECKING" "MONEY_MARKET" "MOBILE_PHONE_NUMBER" "NOT_USED_FOR_THIS_BANK" "PERSONAL" "REGULAR_CHECKING" "SAVING_ACCOUNT" 
 
Type of bank account.
 
account_number
 required 
string
 
Bank account number.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "account_number": "100169168",
  • "account_type": "ACCOUNT_NUMBER",
  • "external_id": "12345678A"
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2019-11-19T15:57:46+0100",
  • "customer": {
    },
  • "customer_account": {
    }
}
Update account 
This method updates the data associated with a bank account of a user in the system.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
uuid
 required 
string
 
Unique identifier of the user's account.
 
external_id
 required 
string
 
External ID provided by the merchant to uniquely identify a customer.
 
account_type
 required 
string (AccountType) 
 Enum: "ACCOUNT_NUMBER" "BUSINESS" "ACCOUNT_CLABE" "CARD_NUMBER" "INTEREST_CHECKING" "MONEY_MARKET" "MOBILE_PHONE_NUMBER" "NOT_USED_FOR_THIS_BANK" "PERSONAL" "REGULAR_CHECKING" "SAVING_ACCOUNT" 
 
Type of bank account.
 
account_number
 required 
string
 
Bank account number.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "uuid": "9B5DDCC2-24A9-4157-A56D-193EB9EF3966",
  • "external_id": "12345678A",
  • "account_type": "ACCOUNT_NUMBER",
  • "account_number": "100169168"
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2019-11-19T16:00:36+0100",
  • "customer": {
    },
  • "customer_account": {
    }
}
Delete account 
This method eliminates the data associated with a bank account of a user in the system
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
uuid
 required 
string
 
Unique identifier of the user's account.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "uuid": "9B5DDCC2-24A9-4157-A56D-193EB9EF3966"
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2019-11-19T16:40:23+0100",
  • "customer_account": {
    }
}
Get account 
Through this method the data associated with a bank account of a user in the system is obtained.
 
path Parameters
uuid
 required 
string
 
 Example:  1F405EA3-9798-42A6-9E87-BD347EF67F55
Unique identifier of the user's account.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
uuid
 required 
string
 
Unique identifier of the user's account.
 
Responses
 Request samples 
Content type
application/json
{
  • "uuid": "9B5DDCC2-24A9-4157-A56D-193EB9EF3966"
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2019-11-19T16:24:21+0100",
  • "customer_account": {
    }
}
Create address 
This method creates the data associated with an address of a user in the system.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
address1
 required 
string
 
Line 1 of the address (max. 50 characters).
 
address2
string Nullable 
 
Line 2 of the address (max. 50 characters).
 
address3
string Nullable 
 
Line 3 of the address (max. 50 characters).
 
city
 required 
string
 
City.
 
country
 required 
string
 
ISO 3166 three-letter alphanumeric code of the country.
 
default
 required 
boolean
 
Set as the default address. If the customer has a default address, it will be used unless a different one is provided.
 
external_id
 required 
string
 
External ID provided by the merchant to uniquely identify a customer.
 
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
state_code
 required 
string
 
State or province.
 
type
 required 
string (AddressType) 
 Enum: "OTHER" "BILLING" "SHIPPING" 
 
Type of address.
 
zip_code
 required 
string
 
Zip code.
 
Responses
 Request samples 
Content type
application/json
{
  • "address1": "Ronda",
  • "address2": "Magdalena",
  • "address3": "número 20",
  • "city": "Castellón",
  • "country": "ESP",
  • "default": false,
  • "external_id": "12345678A",
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "state_code": "Castellón",
  • "zip_code": "12006"
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2019-11-19T16:47:48+0100",
  • "customer": {
    },
  • "customer_address": {
    }
}
Update address 
This method updates the data associated to an address UUID. The type of address cannot be updated.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
uuid
 required 
string
 
Unique identifier of the user's address.
 
address1
 required 
string
 
Line 1 of the address (max. 50 characters).
 
address2
string Nullable 
 
Line 2 of the address (max. 50 characters).
 
address3
string Nullable 
 
Line 3 of the address (max. 50 characters).
 
city
 required 
string
 
City.
 
country
 required 
string
 
ISO 3166 three-letter alphanumeric code of the country.
 
default
 required 
boolean
 
Set as the default address. If the customer has a default address, it will be used unless a different one is provided.
 
external_id
 required 
string
 
External ID provided by the merchant to uniquely identify a customer.
 
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
state_code
 required 
string
 
State or province.
 
type
 required 
string (AddressType) 
 Enum: "OTHER" "BILLING" "SHIPPING" 
 
Type of address.
 
zip_code
 required 
string
 
Zip code.
 
Responses
 Request samples 
Content type
application/json
{
  • "uuid": "9B5DDCC2-24A9-4157-A56D-193EB9EF3966",
  • "address1": "Ronda",
  • "address2": "Magdalena",
  • "address3": "número 20",
  • "city": "Castellón",
  • "country": "ESP",
  • "default": false,
  • "external_id": "12345678A",
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "state_code": "Castellón",
  • "zip_code": "12006"
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2019-11-19T16:54:54+0100",
  • "customer": {
    },
  • "customer_address": {
    }
}
Delete address 
This method eliminates the data associated with an address of a user in the system.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
uuid
 required 
string
 
Unique identifier of the user's address.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "uuid": "B7B20B82-0112-464F-BE0F-2905BA84CDED"
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2019-11-19T17:04:32+0100",
  • "customer_address": {
    }
}
Get address 
Retrieve a customer's address, given its UUID.
 
path Parameters
uuid
 required 
string
 
 Example:  1f405ea3-9798-42a6-9e87-bd347ef67f55
Address UUID
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Responses
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2019-11-19T16:58:57+0100",
  • "customer_address": {
    }
}
Create profile 
This method creates a new profile associated to the user in the system.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
external_id
 required 
string
 
External ID provided by the merchant to uniquely identify a customer.
 
first_name
 required 
string
 
First name of the customer.
 
last_name
 required 
string
 
Last name of the customer.
 
cardholder_name
string
 
Cardholder name.
 
document_identification_issuer_type
string (DocumentIdentificationIssuer) 
 Enum: "STATE_GOVERNMENT" "FEDERAL_GOVERNMENT" "MONEY_TRANSMITTER" "PROFESSIONAL_ASSOCIATION" 
 
Issuer of the identification document of the customer.
 
document_identification_type
string (DocumentIdentificationType) 
 Enum: "ALIEN_REGISTRATION_CARD" "ELECTOR_CREDENTIAL" "FISCAL_IDENTIFICATION_CODE" "ORIGIN_COUNTRY_IDENTIFICATION_CODE" "FOREIGN_IDENTIFICATION_DOCUMENT" "NATIONAL_IDENTITY_DOCUMENT" "OTHER_PHYSICAL_PERSON_DOCUMENTS" "DRIVER_LICENSE" "CONSULAR_REGISTRATION" "UNDER_AGE" "RESIDENCE_CARD" "TAX_IDENTIFICATION_NUMBER" "NON_DRIVER_LICENSE_PHOTO_ID" "VALID_PASSPORT" "DIPLOMAT_IDENTITY_CARD" "US_GOVERNMENT_ISSUER_ID" "UNIQUE_ID_ISSUED_BY_MT" 
 
Type of customer identification document.
 
document_identification_number
string Nullable 
 
Identification number.
 
email
string
 
Email of the customer.
 
 required 
object (Phone) 
 
The customer's phone number.
 
 required 
object (Phone) 
 
The customer's phone number.
 
 required 
object (Phone) 
 
The customer's phone number.
 
 required 
object (Phone) 
 
The customer's phone number.
 
birthdate
string Nullable 
 
Birth date of the customer in YYYY-MM-DD format.
 
source_of_funds
string Nullable 
 
Source of funds of the customer.
 
occupation
string Nullable 
 
Occupation of the customer.
 
social_security_number
string Nullable 
 
Social security number of the customer.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "341f7de8e6fc49da8d8736473af6b03a",
  • "external_id": "1024",
  • "first_name": "Paco",
  • "last_name": "García",
  • "cardholder_name": "Paco Garcia",
  • "document_identification_issuer_type": "STATE_GOVERNMENT",
  • "document_identification_type": "ALIEN_REGISTRATION_CARD",
  • "document_identification_number": "12345678A",
  • "email": "aaronarriero_.@gmail.co.com",
  • "phone": {
    },
  • "work_phone": {
    },
  • "home_phone": {
    },
  • "mobile_phone": {
    },
  • "occupation": "ball juggler",
  • "social_security_number": "1212121212",
  • "birthdate": "1986-03-06T00:00:00.000Z",
  • "source_of_funds": "Bank"
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2019-11-19T14:06:39+0100",
  • "customer": {
    },
  • "customer_profile": {
    }
}
Update profile 
This method updates an existing profile of a user in the system.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
external_id
 required 
string
 
External ID provided by the merchant to uniquely identify a customer.
 
first_name
 required 
string
 
First name of the customer.
 
last_name
 required 
string
 
Last name of the customer.
 
cardholder_name
string
 
Cardholder name.
 
document_identification_issuer_type
string (DocumentIdentificationIssuer) 
 Enum: "STATE_GOVERNMENT" "FEDERAL_GOVERNMENT" "MONEY_TRANSMITTER" "PROFESSIONAL_ASSOCIATION" 
 
Issuer of the identification document of the customer.
 
document_identification_type
string (DocumentIdentificationType) 
 Enum: "ALIEN_REGISTRATION_CARD" "ELECTOR_CREDENTIAL" "FISCAL_IDENTIFICATION_CODE" "ORIGIN_COUNTRY_IDENTIFICATION_CODE" "FOREIGN_IDENTIFICATION_DOCUMENT" "NATIONAL_IDENTITY_DOCUMENT" "OTHER_PHYSICAL_PERSON_DOCUMENTS" "DRIVER_LICENSE" "CONSULAR_REGISTRATION" "UNDER_AGE" "RESIDENCE_CARD" "TAX_IDENTIFICATION_NUMBER" "NON_DRIVER_LICENSE_PHOTO_ID" "VALID_PASSPORT" "DIPLOMAT_IDENTITY_CARD" "US_GOVERNMENT_ISSUER_ID" "UNIQUE_ID_ISSUED_BY_MT" 
 
Type of customer identification document.
 
document_identification_number
string Nullable 
 
Identification number.
 
email
string
 
Email of the customer.
 
 required 
object (Phone) 
 
The customer's phone number.
 
 required 
object (Phone) 
 
The customer's phone number.
 
 required 
object (Phone) 
 
The customer's phone number.
 
 required 
object (Phone) 
 
The customer's phone number.
 
birthdate
string Nullable 
 
Birth date of the customer in YYYY-MM-DD format.
 
source_of_funds
string Nullable 
 
Source of funds of the customer.
 
occupation
string Nullable 
 
Occupation of the customer.
 
social_security_number
string Nullable 
 
Social security number of the customer.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "341f7de8e6fc49da8d8736473af6b03a",
  • "external_id": "1024",
  • "first_name": "Paco",
  • "last_name": "García",
  • "cardholder_name": "Paco Garcia",
  • "document_identification_issuer_type": "STATE_GOVERNMENT",
  • "document_identification_type": "ALIEN_REGISTRATION_CARD",
  • "document_identification_number": "12345678A",
  • "email": "aaronarriero_.@gmail.co.com",
  • "phone": {
    },
  • "work_phone": {
    },
  • "home_phone": {
    },
  • "mobile_phone": {
    },
  • "occupation": "ball juggler",
  • "social_security_number": "1212121212",
  • "birthdate": "1986-03-06T00:00:00.000Z",
  • "source_of_funds": "Bank"
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2019-11-19T15:04:39+0100",
  • "customer": {
    },
  • "customer_profile": {
    }
}
Get profile 
Retrieve a customer's profile.
 
path Parameters
external_id
 required 
string
 
 Example:  12345678A
External ID provided by the merchant to uniquely identify a customer.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
external_id
 required 
string
 
External ID provided by the merchant to uniquely identify a customer.
 
Responses
 Request samples 
Content type
application/json
{
  • "external_id": "12345678A"
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2019-11-19T15:09:31+0100",
  • "customer_profile": {
    }
}
Card Present
In the realm of electronic payments, the term "Card Present" refers to transactions where the physical payment card is present at the time of the transaction. These types of payments are typically made through a physical point of sale (POS) terminal, where the card is swiped, inserted (in the case of chip cards), or tapped (in the case of contactless or NFC cards) on the device.
 
This section describes all the available endpoints in Paylands to execute operations from physical devices. These endpoints will always return the response synchronously.
 
Charge 
This endpoint allows processing a payment initiated at a POS.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
 required 
object
 
If the track2 field is provided, the pan, expiration_month, and expiration_year fields must not be included. If track2 is not sent, the pan, expiration_month, and expiration_year fields are mandatory.
 
amount
 required 
number  >= 0 
 
Amount to charge, in the fractional currency of your choice. An amount of 100 using the currency EUR is equal to 1€.
 
currency
 required 
string
 
3 letter currency code.
 
mid
 required 
string
 
Merchant identifier.
 
stan
 required 
string
 
Transaction identifier used to trace its transactional flow.
 
card_reading_method
 required 
string
 Enum: "KEY_ENTRY" "BAR_CODE" "MAGNETIC_STRIPE" "ICC" "NFC" 
 
Defines how the card has been provided.
 
emv_data
 required 
string
 
Encrypted data including card and transaction information.
 
card_sequence_number
 required 
string  3 characters 
 
Card identifier being used to differentiate cards with the same PAN.
 
 required 
object
 
 required 
object
 
Responses
 Request samples 
Content type
application/json
{
  • "card": {
    },
  • "amount": 100,
  • "currency": "EUR",
  • "mid": "123456789",
  • "stan": "836425",
  • "card_reading_method": "ICC",
  • "emv_data": "820219808407A00000000410109505000000800101020880",
  • "card_sequence_number": "004",
  • "pin": {
    },
  • "device": {
    }
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2021-12-28T15:29:49+0100",
  • "order": {
    },
  • "client": {
    }
}
Process a refund 
This endpoint allows processing a refund based on a previous charge.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
amount
 required 
number  >= 0 
 
Amount to refund, in the fractional currency of your choice. An amount of 100 using the currency EUR is equal to 1€.
 
mid
 required 
string
 
Merchant identifier.
 
stan
 required 
string
 
Transaction identifier used to trace its transactional flow.
 
rrn
 required 
string
 
Original transaction's identifier.
 
tid
 required 
string
 
Device's unique identifier.
 
Responses
 Request samples 
Content type
application/json
{
  • "amount": 100,
  • "mid": "123456789",
  • "stan": "836425",
  • "rrn": "59CV8731",
  • "tid": "TerminalID123"
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2021-12-28T15:29:49+0100",
  • "order": {
    },
  • "client": {
    }
}
Cards
Store multiple credit/debit cards 
This endpoint can store multiple credit cards, which can be used in a WebService payments call. The validate and service fields are only necessary in case the card needs to be validated against the bank service.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
 required 
Array of objects
 
List of cards to tokenize.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "cards": [
    ]
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2021-05-19T12:18:49+0200",
  • "cards": [
    ]
}
Store credit/debit card 
This endpoint stores a credit card, so it can be used in a WebService payment call. The validate and service fields are only necessary in case the card needs to be validated against the service.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
card_holder
 required 
string
 
Cardholder name.
 
card_pan
 required 
string
 
Primary account number (PAN).
 
card_expiry_month
 required 
string
 
Expiry month of the card.
 
card_expiry_year
 required 
string
 
Expiry year of the card.
 
customer_ext_id
 required 
string
 
External ID provided by the merchant to uniquely identify a customer.
 
additional
string
 
Free field provided by the merchant. May be used to store any kind of data.
 
url_post
string
 
URL that will receive an HTTP notification containing the payment's outcome.
 
validate
boolean Nullable 
 Default:  false
 
Only necessary if you want the card to be validated. If provided, the service field becomes required, and the card_cvv field may be sent to validate it as well.
 
service
string
 
The UUID of the payment service used to perform the operation.
 
card_cvv
string
 
Card Verification Value (CVV) usually displayed on the back of the card.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "card_holder": "John Doe",
  • "card_pan": "4111111111111111",
  • "card_expiry_month": "12",
  • "card_expiry_year": "19",
  • "customer_ext_id": "user42",
  • "additional": "card12345",
  • "url_post": "https://my.website.com/process",
  • "validate": true,
  • "service": "60A1F4C0-CC58-47A9-A0B9-868F9EF29045",
  • "card_cvv": "123"
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2017-01-12T09:12:58+0100",
  • "Customer": {
    },
  • "Source": {
    }
}
Delete card 
This endpoint deletes a stored credit card.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
card_uuid
 required 
string
 
Unique identifier of the card.
 
customer_external_id
 required 
string
 
External ID provided by the merchant to uniquely identify a customer.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "card_uuid": "C10721E7-1404-45DC-8762-351DD9945D1D",
  • "customer_external_id": "user1234"
}
 Response samples 
Content type
application/json
{
  • "code": 200,
  • "current_time": "2017-01-12T09:12:58+0100",
  • "message": "OK"
}
Revalidate an already tokenized card 
This endpoint validates a card that was previously tokenized. This can be useful in some cases to check if card has funds or is valid. Some payment services require the card_cvv to be provided.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
source_uuid
 required 
string
 
Unique identifier of the payment method used to perform the payment.
 
customer_ext_id
 required 
string
 
External ID provided by the merchant to uniquely identify a customer.
 
service
 required 
string
 
The UUID of the payment service used to perform the operation.
 
card_cvv
string
 
Card Verification Value (CVV) usually displayed on the back of the card.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "source_uuid": "C10721E7-1404-45DC-8762-351DD9945D1D",
  • "customer_ext_id": "12345678A",
  • "service": "60A1F4C0-CC58-47A9-A0B9-868F9EF29045",
  • "card_cvv": "123"
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2017-01-12T09:12:58+0100",
  • "Customer": {
    },
  • "Source": {
    }
}
Set/edit description 
By using this endpoint, a description can be linked to a credit card.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
source_uuid
 required 
string
 
Unique identifier of the payment method used to perform the payment.
 
additional
string
 
Free field provided by the merchant. May be used to store any kind of data.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "source_uuid": "C10721E7-1404-45DC-8762-351DD9945D1D",
  • "additional": "Tarjeta principal"
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2021-12-29T10:14:14+0100",
  • "Customer": {
    },
  • "Source": {
    }
}
Retrieve all cards associated to a customer 
By using this method the user's associated cards are obtained. The customer_ext_id parameter must match the one provided when the payment order was generated or when the card was stored.
 
path Parameters
customer_ext_id
 required 
string
 
 Example:  123fd2
External ID provided by the merchant to uniquely identify a customer.
 
query Parameters
status
string
 
 Example:  status=VALIDATED
Selects which cards will be returned. Two values are allowed:
 
     
  • VALIDATED - Only validated cards will be returned. Validated cards are those that were checked against bank service when user stored them or those that haven been used in a successful payment. This is the value by default.
     
    •  
  • ALL - All customer cards will be returned, both validated and unvalidated.
     
    •  
 
unique
string
 
 Example:  unique=false
When a payment is done within Paylands, it is associated to a customer card. If this card is used in another payment, another entry for this card is created. When fetching cards, the unique parameter decides whether repeated cards need to be returned. Obtaining repeated cards is useful to know how many times a card has been used. Retrieving them without repetition is useful when the purpose is to populate a dropdown to the user, where only different cards need to be shown. Two boolean values are allowed:
 
     
  • true - No repetition. One occurrence per card will be returned.
     
    •  
  • false - Cards may be returned with repetition. This is the value by default.
     
    •  
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Responses
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2017-01-12T09:12:58+0100",
  • "cards": [
    ]
}
View credit/debit card 
Through this endpoint you can obtain the data of a card by his UUID. The response follows the same structure as in the endpoint of storing card.
 
path Parameters
uuid
 required 
string
 
 Example:  1F405EA3-9798-42A6-9E87-BD347EF67F55
Unique identifier of the card.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Responses
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2017-01-12T09:12:58+0100",
  • "Customer": {
    },
  • "Source": {
    }
}
Bank accounts
New bank account 
Endpoint used to store a bank account. The account will be associated with the customer provided in the customer_ext_id parameter.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
customer_ext_id
 required 
string
 
External ID provided by the merchant to uniquely identify a customer.
 
account_holder
 required 
string
 
Account holder name.
 
iban
 required 
string
 
IBAN of the bank account.
 
additional
string
 
Free field provided by the merchant. May be used to store any kind of data.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "account_holder": "John Doe",
  • "iban": "ES9030350000070000000202",
  • "customer_ext_id": "user42",
  • "additional": "bank12345"
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2023-04-20T11:29:05+0200",
  • "Customer": {
    },
  • "Source": {
    }
}
Delete bank account 
This endpoint deletes a stored bank account.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
source_uuid
 required 
string
 
Unique identifier of the payment method used to perform the payment.
 
customer_ext_id
 required 
string
 
External ID provided by the merchant to uniquely identify a customer.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "source_uuid": "C10721E7-1404-45DC-8762-351DD9945D1D",
  • "customer_ext_id": "user1234"
}
 Response samples 
Content type
application/json
{
  • "code": 200,
  • "current_time": "2017-01-12T09:12:58+0100",
  • "message": "OK"
}
Retrieve all bank accounts associated to a customer 
By using this method the user's associated bank accounts are obtained. The customer_ext_id parameter must match the one provided when the payment order was generated or when the bank account was stored.
 
path Parameters
customer_ext_id
 required 
string
 
 Example:  123fd2
External ID provided by the merchant to uniquely identify a customer.
 
query Parameters
status
string
 
 Example:  status=VALIDATED
Selects which bank accounts will be returned. Two values are allowed:
 
     
  • VALIDATED - Only validated bank accounts will be returned. Validated bank accounts are those that were checked against bank service when user stored them or those that haven been used in a successful payment. This is the value by default.
     
    •  
  • ALL - All customer bank accounts will be returned, both validated and unvalidated.
     
    •  
 
unique
string
 
 Example:  unique=false
When a payment is done within Paylands, it is associated to a customer card. If this card is used in another payment, another entry for this card is created. When fetching bank accounts, the unique parameter decides whether repeated bank accounts need to be returned. Obtaining repeated bank accounts is useful to know how many times a card has been used. Retrieving them without repetition is useful when the purpose is to populate a dropdown to the user, where only different bank accounts need to be shown. Two boolean values are allowed:
 
     
  • true - No repetition. One occurrence per card will be returned.
     
    •  
  • false - Bank accounts may be returned with repetition. This is the value by default.
     
    •  
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Responses
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2023-04-20T12:49:29+0200",
  • "banks": [
    ]
}
View bank account 
Through this endpoint you can obtain the data of a bank account by its UUID.
 
path Parameters
uuid
 required 
string
 
 Example:  1F405EA3-9798-42A6-9E87-BD347EF67F55
Unique identifier of the bank account.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Responses
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2023-04-20T15:33:24+0200",
  • "bank": {
    }
}
Update external ID
Update external ID of cards, dynamic cards and bank accounts. 
Using this method you can modify the owner of a card already stored in Paylands. Simply indicate the uuid of the card, dynamic card or bank account that you want to update in the url. After this, indicate in the body of the request the current external_id (old_external_id) and the new one (new_external_id).
 
path Parameters
source_uuid
 required 
string
 
 Example:  1F405EA3-9798-42A6-9E87-BD347EF67F55
Unique identifier of payment method.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
old_external_id
 required 
string
 
External ID provided by the merchant to uniquely identify a customer.
 
new_external_id
 required 
string
 
External ID provided by the merchant to uniquely identify a customer.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "341f7de8e6fc49da8d8736473af6b03a",
  • "old_external_id": "1024",
  • "new_external_id": "102455"
}
 Response samples 
Content type
application/json
{
  • "code": 200,
  • "current_time": "2017-01-12T09:12:58+0100",
  • "message": "OK"
}
MoTo campaigns
Payment link delivery (CSV) 
MoTo campaigns can be created in two different ways: using the MoTo campaigns section in the control panel or using an endpoint in Paylands API.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
description
 required 
string
 
A short description about the campaign.
 
expires_at
 required 
string
 
Date after which the payments expire and can no longer be attempted. Payments expire at 00:00:00 on the provided date.
 
file
 required 
string
 
CSV in base64, starting with the text: data:text/csv;base64,
 
filename
string Nullable 
 
Name of the .csv file.
 
service_uuid
 required 
string
 
The UUID of the payment service used to perform the operation.
 
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
subject
 required 
string Nullable 
 
This value will be sent as subject if the type is "EMAIL". In the case of SMS, the name of the merchant will be indicated with a maximum of 11 characters.
 
type
 required 
string (MoToType) 
 Enum: "PHONE" "MAIL" "CUSTOM_DELIVERY" 
 
Delivery method of the MoTo payments.
 
Responses
 Request samples 
Content type
application/json
{
  • "description": "Campaña de Navidad 2019",
  • "expires_at": "2017-11-11T00:00:00.000Z",
  • "file": "data:text/csv;base64,QU1PVU5ULE9QRVJBVElWRSxERVNUSU5BVElPTixDVVNUT01FUl9FWFRfSUQsQURESVRJT05BTCxTRUNVUkUsVVJMX1BPU1QsVVJMX09LLFVSTF9LTyxDQVJEX1RFTVBMQVRFLE1PVE9fVEVNUExBVEUsRENDX1RFTVBMQVRFCjEsREVGRVJSRUQsc3VjY2Vzc0BzaW11bGF0b3IuYW1hem9uc2VzLmNvbSxleHRlcm5hbElELGFkZGl0aW9uYWwsRkFMU0UsaHR0cDovL3VybC5wb3N0LGh0dHA6Ly91cmwub2ssaHR0cDovL3VybC5rbyxDRDVGMzU0MC1CMkNCLTRDNjctQUU2Qi1GNzZFRDkzREU2QzEsRUVCRjEwMjItNkRCMi00NURCLTgxN0QtQTg3QjA5QUU4NDFCLDQwMTExRkU4LTlCMzItNDNFMy1BNEFFLTk3QzdCRTZEMTlDNQ==",
  • "filename": "test.csv",
  • "service_uuid": "60A1F4C0-CC58-47A9-A0B9-868F9EF29045",
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "subject": "Navidad 2019",
  • "type": "PHONE"
}
 Response samples 
Content type
application/json
{
  • "code": 200,
  • "current_time": "2019-05-30T12:52:54+0200",
  • "detail": {
    },
  • "message": "OK",
  • "payments": [
    ]
}
Payment link delivery (JSON) 
In order to generate a payment link delivery, the following fields must be sent to the API.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
description
 required 
string
 
A short description about the delivery.
 
expires_at
 required 
string
 
Date after which the payments expire and can no longer be attempted. Payments expire at 00:00:00 on the provided date.
 
service_uuid
 required 
string
 
The UUID of the payment service used to perform the operation.
 
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
subject
 required 
string Nullable 
 
This value will be sent as subject if the type is "EMAIL". In the case of SMS, the name of the merchant will be indicated with a maximum of 11 characters.
 
type
 required 
string (MoToType) 
 Enum: "PHONE" "MAIL" "CUSTOM_DELIVERY" 
 
Delivery method of the MoTo payments.
 
Array of objects
 
Responses
 Request samples 
Content type
application/json
{
  • "description": "Campaña de Navidad 2019",
  • "expires_at": "2017-11-11T00:00:00.000Z",
  • "service_uuid": "60A1F4C0-CC58-47A9-A0B9-868F9EF29045",
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "subject": "Navidad 2019",
  • "type": "PHONE",
  • "payments": [
    ]
}
 Response samples 
Content type
application/json
{
  • "code": 200,
  • "current_time": "2019-05-30T12:52:54+0200",
  • "detail": {
    },
  • "message": "OK",
  • "payments": [
    ]
}
Download receipt certificate 
You can download the certificate of receipt of a MoTo payment through your uuid. Available for MoTo campaigns via Email and SMS.
 
path Parameters
moto_payment_uuid
 required 
string
 
 Example:  C089B1BF-A4FA-4B0F-A5FE-F21C5BFEFC27
Unique identifier of the MoTo payment.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Responses
 Response samples 
Content type
application/json
{
  • "certificate": "JVBERi0xLjYKJfbk/N8KMSAwIG9iago8PAovQWNyb0Zvcm0gMiAwIFIKL01ldGFkYXRhIDMg...",
  • "code": 200,
  • "current_time": "2021-02-15T16:55:20+0100",
  • "message": "OK"
}
Consult MoTo orders 
Moto orders can be consulted in two different ways : using the control panel or using an endpoint in Paylands API.
 
path Parameters
moto_detail_uuid
 required 
string
 
 Example:  2FE8B569-6168-428D-9A3A-8BC265215A1B
Unique identifier of the MoTo campaign.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Responses
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2019-05-30T12:52:54+0200",
  • "orders": {
    }
}
Batch operations
Payments file 
Queues a payment batch file.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
data
 required 
string
 
CSV file encoded in base64.
 
execute_at
string Nullable 
 
Date after which the file will be processed. If this date is not specified, the file will be queued for processing as soon as it is uploaded.
 
filename
 required 
string
 
Name of the file under which the payments will be grouped.
 
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
Responses
 Request samples 
Content type
application/json
{
  • "data": "QU1PVU5ULENBUkQsQ1VTVE9NRVJfRVhURVJOQUxfSUQsU0VSVklDRSxBRERJVElPTkFMLFVSTF9QT1NUDQoxMjAzNSxFNzZBNTdGRi00REJDLTRBM0QtQjZFMy0wNTIwRThCMTNFM0YsMzA4LDExNEFCNDI0LTAyM0ItNEUxMy",
  • "execute_at": "2017-11-11T11:11:11.000Z",
  • "filename": "test.csv",
  • "signature": "121149a0ba5361191d740fa898784a8b"
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2017-10-26T17:28:06+0200"
}
Refunds file 
Queues a refund batch file.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
data
 required 
string
 
CSV file encoded in base64.
 
execute_at
string Nullable 
 
Date after which the file will be processed. If this date is not specified, the file will be queued for processing as soon as it is uploaded.
 
filename
 required 
string
 
Name of the file under which the refunds will be grouped.
 
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
Responses
 Request samples 
Content type
application/json
{
  • "data": "T1JERVJfVVVJRCxBTU9VTlQKMjY3Njk3NjMtQTJDOS00QUI4LTgwRDQtOTVERDgyNEUzNzVBLDEKMjY3Njk3NjMtQTJDOS00QUI4LTgwRDQtOTVERDgyNEUzNzVBLDIKMjY3Njk3NjMtQTJDOS00QUI4LTgwRDQtOTVERDgyNEUzNzVBLDMyMjIyCg==",
  • "execute_at": "2017-11-11T11:11:11.000Z",
  • "filename": "test.csv",
  • "signature": "121149a0ba5361191d740fa898784a8b"
}
 Response samples 
Content type
application/json
{
  • "code": 200,
  • "current_time": "2017-10-26T17:28:06+0200",
  • "errors": [
    ],
  • "message": "OK"
}
Subscriptions
Paylands allows the merchant to perform recurrent payment by using subscription. In order to use this feature, it's needded a product to be registered (the one thas is being offered) - for example, a streaming service. Having this done, one or more plans can be registered for this product - for example, a 10€/month installment and a 100€/year installment.
 
When registering subscriptions, we suggest designing a custom payment form where customer can select the desired plan and the card tha will be charged. Once the charge day has been reached, client will be charged and a notification will be sent to the merchant with the payment's information including whether it was successful or not. All this transactions will be carried out within Paylands' API.
 
Plans are flexible, which means they can be charged daily, weekly, monthly or yearly. It's also possible to configured the payment each X days, weeks or months. The first installment can be delayed several days or weeks so clients can cancel their subscription before any charge is made. Once a user has been registered, it can be obtained next payment's date, including his subscription status - payment pending, paid or cancelled.
 
Create company 
The first step in order to use Paylands' subscriptions is being registered, creating a subscription profile where all products, plans and subscriptions will be associated. It's as easy as making a request to the following endpoint.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Responses
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2019-12-04T11:59:41+0100",
  • "company": {
    }
}
Create product 
A product identifies the service being offered and can include one or several plan with different installments. Products that were registed as sandbox will not use real money on their charges.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
name
 required 
string
 
Product name.
 
external_id
 required 
string
 
External ID provided by the merchant to uniquely identify a product.
 
notification_url
string
 
URL that will receive an HTTP notification when payment changes status.
 
Responses
 Request samples 
Content type
application/json
{}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2019-12-04T15:29:10+0100",
  • "product": {}
}
List products 
Lists all created products.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Responses
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2019-12-04T15:29:12+0100",
  • "products": [
    ]
}
Get product 
Get a product by external ID.
 
path Parameters
product_external_id
 required 
string
 
 Example:  product
Unique external ID of the product.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Responses
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2020-03-05T16:46:51+0100",
  • "product": {}
}
Remove product 
Removes a product, given its external ID. When removing a product, its subscriptions won't be cancelled.
 
path Parameters
product_external_id
 required 
string
 
 Example:  product
Unique external ID of the product.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b"
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2019-12-04T15:28:25+0100",
  • "deleted": 1
}
Get a payment 
Get a payment by ID
 
path Parameters
payment_id
 required 
string
 
 Example:  5e6116949d3a0c6b2e56826c
ID of the subscription payment.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Responses
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2020-03-05T16:13:31+0100",
  • "payment": {
    }
}
List payments 
List all created payments.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Responses
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2020-03-05T16:23:23+0100",
  • "payments": [
    ]
}
Create plan 
A plan determines the installment amount and frequency that users will be charged, among other features. A plan is only associated to one product.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
name
 required 
string
 
The plan name.
 
external_id
 required 
string
 
External ID provided by the merchant to uniquely identify a plan.
 
product
 required 
string
 
External ID provided by the merchant to uniquely identify a plan.
 
amount
 required 
number  >= 0 
 
Amount to charge, in the fractional currency of your choice. An amount of 100 using the currency EUR is equal to 1€.
 
interval
 required 
number
 
Interval in the unit specified in the field interval_type that determines how often the subscription should be charged.
 
interval_type
 required 
string
 
Determines how often the subscription should be charged. Allowed values are "DAILY", "WEEKLY", "MONTHLY", "ANNUAL"
 
trial_available
boolean
 
By default, false. Whether or not there is a trial period. The customer will not be charged until this trial ends.
 
interval_offset
number
 
Interval in the unit specified in the field interval_offset_type that determines the unit of time used on the trial period of the subscription.
 
interval_offset_type
string
 
Determines how long the trial lasts. Allowed values are "DAILY", "WEEKLY", "MONTHLY", "ANNUAL"
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "name": "Other plan",
  • "external_id": "other_plan",
  • "product": "other_product",
  • "amount": 100,
  • "interval": 1,
  • "interval_type": "MONTHLY",
  • "trial_available": false,
  • "interval_offset": null,
  • "interval_offset_type": "WEEKLY"
}
 Response samples 
Content type
application/json
{
  • "code": 200,
  • "current_time": "2019-12-04T16:30:29+0100",
  • "message": "OK",
  • "plan": {
    }
}
List plans 
List all plans.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Responses
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2019-12-04T16:55:28+0100",
  • "plans": [
    ]
}
Get a plan 
Get a plan by external ID.
 
path Parameters
plan_external_id
 required 
string
 
 Example:  plan
Unique external ID of the plan.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Responses
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2020-03-05T16:37:02+0100",
  • "plan": {
    }
}
Remove plan 
Removes a plan, given its external ID. When removing a plan, its subscriptions won't be cancelled.
 
path Parameters
plan_external_id
 required 
string
 
 Example:  plan
Unique external ID of the plan.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b"
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2019-12-04T16:30:29+0100",
  • "deleted": 1
}
Subscribe a customer 
This endpoint subscribes a customer to the specified plan, given plan's external ID and customer's ID, amon other fields. If trial_available field within the plan is false, an instant charge is carried out after subscribing the customer. If any of the fields (service UUID or card UUID, for example) is incorrect, subscription will be registered but charged won't be able to be made. In this case, the status field will be FAILED_NOTIFICATION. An example of this notification that would be sent to the product's notification_url would be the following one:
 
{
    "payment_id": "5dfa00a4229c1a127749ae9e",
    "subscription": "5dfa00a4229c1a127749ae9d",
    "plan": "plan_external_id",
    "product": "product_external_id",
    "customer": "customer_external_id",
    "company": "FF255421-F4B7-47E9-9816-949F5F03DE6F",
    "status": "FAILED_NOTIFICATION",
    "payment_date": "2019-12-18T10:34:12.640Z",
    "payment_number": 1,
    "attempt": 1,
    "amount": 1,
    "currency": "978"
}
sub_diag_seq_1
 
If all parameters are correct, charge will be made and Paylands will send the expected notification to the subscription's post_url. It will also be sent a notification to the product's notification_url. An example of this notification can be seen in the second response to the following endpoint. sub_diag_seq_2
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
plan
 required 
string
 
External ID provided by the merchant to uniquely identify a plan.
 
customer
 required 
string
 
External ID provided by the merchant to uniquely identify a customer.
 
 required 
object
 
Additional data required to perform the payment.
 
total_payment_number
 required 
number
 
Total number of payments that will be charged during the subscription period.
 
payment_attempts_limit
 required 
number
 
Maximum amount of retries to charge for any subscription payment. If the payment fails X times consecutively, the subscription is cancelled.
 
initial_date
string Nullable 
 
By default, the current date. If provided it specifies when the first payment will be performed.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "customer": "customer name",
  • "plan": "plan",
  • "additional_data": {
    },
  • "initial_date": "2019",
  • "payment_attempts_limit": 3,
  • "total_payment_number": 3
}
 Response samples 
Content type
application/json
{
  • "amount": 1,
  • "attempt": 1,
  • "company": "FF255421-F4B7-47E9-9816-949F5F03DE6F",
  • "currency": "978",
  • "customer": "customer_external_id",
  • "payment_date": "2019-12-18T10:34:12.640Z",
  • "payment_id": "5dfa00a4229c1a127749ae9e",
  • "payment_number": 1,
  • "plan": "plan_external_id",
  • "product": "product_external_id",
  • "status": "PAID",
  • "subscription": "5dfa00a4229c1a127749ae9d"
}
List subscriptions 
Lists all subscriptions.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Responses
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2019-12-05T08:42:24+0100",
  • "subscriptions": [
    ]
}
Get a subscription 
Get a subscription by ID.
 
path Parameters
subscription_id
 required 
string
 
 Example:  5de7b52ac4d347306fd59ec5
Unique identifier of the subscription.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Responses
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2020-03-05T16:51:27+0100",
  • "subscription": {
    }
}
Cancel a subscription 
Cancels a subscription using its ID.
 
path Parameters
subscription_id
 required 
string
 
 Example:  5de7b52ac4d347306fd59ec5
Unique identifier of the subscription.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b"
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2019-12-04T17:40:46+0100",
  • "deleted": 1
}
POSMS (Physical devices)
Paylands allows the merchant to make physical payments using smart payment terminals. To use this service, it is necessary for the support team to register the merchant on the platform and configure the necessary devices with the credentials of the Credorax service that will be used in each of them. Once the merchant has the smart payment terminals, the merchant can start processing payments through them. Simulation It is possible, in sandbox environment, to simulate the physical devices behaviour, without needing to own them. To achieve this, it is necessary that Paylands' support team assigns you a virtual device with the SIMULATION communication type. These devices can be obtained using the API, in the same way physical devices will be obtained in production environment. When you execute a payment or a refund on one of these virtual devices, this transaction will be processed automatically after 10 seconds, simulating the action of swiping the card through the physical device. You can configure the type of response expected based on the payment amount: - Cancelled: the payment will be processed as CANCELLED if the amount is 100.
 
     
  • Refused: the payment will be processed as REFUSED if the amount is 200.
    •  
  • Paid: the payment will be processed as PAID if the amount is any other.
    •  
 
List physical devices 
Lists the physical devices associated to a merchant.
 
query Parameters
identifier
string
 
 Example:  identifier=611629d29a5b401507c11f7e
Unique identifier of the physical device.
 
service
string
 
 Example:  service=2A207771-A772-48B1-A56F-F72A2B74D768
Unique identifier of the payment service.
 
terminal_id
string
 
 Example:  terminal_id=PPESNA0001
Identifier of the acquirer's device.
 
communication_type
string
 
 Example:  communication_type=SOCKET
Protocol through which the communication with the physical device will be established.
 
active
string
 
 Example:  active=SOCKET
Whether or not the device is enabled for usage.
 
configured
string
 
 Example:  configured=true
Whether or not the device has been properly configured for the communication and usage.
 
created_at_from
string
 
 Example:  created_at_from=202112312359
Match the physical devices created from a certain date in YYYYMMDDHHmm format.
 
created_at_to
string
 
 Example:  created_at_to=202112312359
Match the physical devices created until a certain date in YYYYMMDDHHmm format.
 
updated_at_from
string
 
 Example:  updated_at_from=202112312359
Match the physical devices updated from a certain date in YYYYMMDDHHmm format.
 
updated_at_to
string
 
 Example:  updated_at_to=202112312359
Match the physical devices updated until a certain date in YYYYMMDDHHmm format.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Responses
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2021-11-22T12:00:28+0100",
  • "devices": [
    ]
}
Get device 
Obtain the information of a physical device by its ID.
 
path Parameters
id
 required 
string
 
 Example:  611629d29a5b401507c11f7e
Unique identifier of the physical device.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Responses
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2021-11-22T12:00:28+0100",
  • "device": {
    }
}
Send payment 
This endpoint allows the merchant to send an order with the AUTHORIZATION operation to the chosen physical device.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
device
 required 
string
 
Unique identifier of physical device.
 
amount
 required 
number  >= 0 
 
Amount to charge, in the fractional currency of your choice. An amount of 100 using the currency EUR is equal to 1€.
 
description
 required 
string
 
Payment description. This field is what users will see on their bank statement in bank transfer transactions.
 
customer_ext_id
string
 
External ID provided by the merchant to uniquely identify a customer.
 
additional
string
 
Free field provided by the merchant. May be used to store any kind of data.
 
url_post
string
 
URL that will receive an HTTP notification containing the payment's outcome.
 
reference
string Nullable 
 
The reference of the order. May be used as an external identifier or to avoid duplicate payments.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "device": "611629d29a5b401507c11f7e",
  • "amount": 100,
  • "description": "Order's description",
  • "customer_ext_id": "12345678A",
  • "additional": "Additional info",
  • "url_post": "https://mysite.com/payment/result",
  • "reference": "XXX1234ABC"
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2021-11-23T16:31:47+0100",
  • "order": {
    },
  • "client": {
    },
  • "device": {
    }
}
Send pre-authorization 
This endpoint allows the merchant to send an order with the DEFERRED operative to the chosen physical device.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
device
 required 
string
 
Unique identifier of physical device.
 
amount
 required 
number  >= 0 
 
Amount to charge, in the fractional currency of your choice. An amount of 100 using the currency EUR is equal to 1€.
 
description
 required 
string
 
Payment description. This field is what users will see on their bank statement in bank transfer transactions.
 
customer_ext_id
string
 
External ID provided by the merchant to uniquely identify a customer.
 
additional
string
 
Free field provided by the merchant. May be used to store any kind of data.
 
url_post
string
 
URL that will receive an HTTP notification containing the payment's outcome.
 
reference
string Nullable 
 
The reference of the order. May be used as an external identifier or to avoid duplicate payments.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "device": "611629d29a5b401507c11f7e",
  • "amount": 100,
  • "description": "Order's description",
  • "customer_ext_id": "12345678A",
  • "additional": "Additional info",
  • "url_post": "https://mysite.com/payment/result",
  • "reference": "XXX1234ABC"
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2021-11-23T16:31:47+0100",
  • "order": {
    },
  • "client": {
    },
  • "device": {
    }
}
Send confirmation 
This endpoint allows the merchant to send a confirmation of a pre-authorization to the chosen physical device.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
device
 required 
string
 
Unique identifier of physical device.
 
order_uuid
 required 
string
 
Unique identifier of the order.
 
amount
number  >= 0 
 
Amount to charge, in the fractional currency of your choice. An amount of 100 using the currency EUR is equal to 1€.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "device": "611629d29a5b401507c11f7e",
  • "order_uuid": "4DE116C9-0064-4BCA-A5D0-1D69A8E972FD",
  • "amount": 100
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2021-11-23T16:34:56+0100",
  • "order": {
    },
  • "client": {
    },
  • "device": {
    }
}
Send cancellation 
This endpoint allows the merchant to send a cancellation of a pre-authorization to the chosen physical device.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
device
 required 
string
 
Unique identifier of physical device.
 
order_uuid
 required 
string
 
Unique identifier of the order.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "device": "611629d29a5b401507c11f7e",
  • "order_uuid": "4DE116C9-0064-4BCA-A5D0-1D69A8E972FD"
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2021-11-23T16:34:56+0100",
  • "order": {
    },
  • "client": {
    },
  • "device": {
    }
}
Send refund 
You can send the amount field if you need to make a partial refund. If it is not sent, the remaining amount to be refunded will be taken as the value.
 
header Parameters
Authorization
 required 
string
 
 Example:  Basic VGhpc0lzWW91ckFQSUtleUtlZXBJdFNhZmU=
Authorization header containing your API key.
 
Request Body schema: application/json
signature
 required 
string
 
Signature paired with the API key. Required in all POST/PUT/DELETE requests.
 
device
 required 
string
 
Unique identifier of physical device.
 
order_uuid
 required 
string
 
Unique identifier of the order.
 
amount
number  >= 0 
 
Amount to refund, in the fractional currency of your choice. An amount of 100 using the currency EUR is equal to 1€.
 
Responses
 Request samples 
Content type
application/json
{
  • "signature": "121149a0ba5361191d740fa898784a8b",
  • "device": "611629d29a5b401507c11f7e",
  • "order_uuid": "4DE116C9-0064-4BCA-A5D0-1D69A8E972FD",
  • "amount": 50
}
 Response samples 
Content type
application/json
{
  • "message": "OK",
  • "code": 200,
  • "current_time": "2021-11-23T16:34:56+0100",
  • "order": {
    },
  • "client": {
    },
  • "device": {
    }
}