Create Payment Instruction

The API creates payment Instructions and enables you to transfer funds to the registered beneficiary.

POST /payments/payments

Body parameters - Request

Name
Location
Type
Format / Values
Description
Required

correlation_id

body

string

correlation_id is an external identifier that you provide to track payments within your own platform or system. This field allows you to link our payment records with your internal transaction records for easier reconciliation and tracking. The correlation_id must be unique across all your payments, if a duplicate correlation_id submitted, the API request will fail

limitations: correlation_id should contain up to 100 characters

No special characters allowed, only “a-z”, “0-9”, “_”, “-“

description

body

string

The remittance info to send as part of the payment

purpose

body

string

/^([A-Z]{4})$/

the purpose of the payment as a 4 letter iso-20022 code. see: <External code sets | ISO20022

No, defaults to SALA

source

body

object

Yes

source.type

body

string

group

type of source (must be group)

source.id

body

string

Yes

target

body

object

Yes

target.type

body

string

contact

target.id

body

string

The id of the target entity (beneficiary)

Yes

approved

body

boolean

Set to true to mark the payment as approved and ready to be executed

amount

body

object

Specifies the amount of the payment

Yes

amount.type

body

string

LAND, SEND

Does the amount refer to the amount credited (LAND), or the amount debited (SEND)

amount.amount

body

number

The amount (up to 3 decimal points)

Yes

amount.currency

body

string

/^[A-Z]{3}$/

If the amount currency is different than the sender (for SEND) or target (for LAND), specify the 3 letter ISO currency code of the payment

execution

body

object

specifies info for the executing date

Yes

execution.type

body

string

SEND, LAND

Does the date refer to the date the funds should arrive (LAND) or the date the funds should be sent (SEND), defaults to amount.type (future support)

execution.date

body

string

date-time

The date this payment should be sent on (for SEND payments) or the date this payment should arrive by (for LAND payments)

Yes

execution.margin

body

integer

number of hours before execution date, this payment may be sent if funds exist

final

body

object

Properties describing the finalization of this payment details

final.is_final

body

boolean

is the amount final

final.expected

body

string

date-time

If the amount is not final yet, when is the final amount expected

attachments

body

array

object

List of files to attach to the payment

attachments[].id

body

string

a unique id to give the attachment

attachments[].title

body

string

A title to give the attachment

attachments[].url

body

string

a url link to the attachment

Yes

user_tags

body

object

A set of key/value pairs to tag the payment with

Body parameters - Response

Name
Type
Format / Values
Description

correlation_id

amount

object

Specifies the amount of the payment

amount.type

string

LAND, SEND

Does the amount refer to the amount credited (LAND), or the amount debited (SEND)

amount.amount

number

The amount (up to 3 decimal points)

amount.currency

string

/^[A-Z]{3}$/

If the amount currency is different than the sender (for SEND) or target (for LAND), specify the 3 letter ISO currency code of the payment

approved

boolean

Has this payment been approved and ready for execution

attachments

array

object

List of files to attach to the payment

attachments[]

object

attachments[].id

string

a unique id to give the attachment

attachments[].title

string

A title to give the attachment

attachments[].url

string

a url link to the attachment

description

string

The remittence info to send as part of the payment

execution

object

specifies info for the executing date

execution.type

string

SEND, LAND

Does the date refer to the date the funds should arrive (LAND) or the date the funds should be sent (SEND), defaults to amount.type (future support)

execution.date

string

date-time

The date this payment should be sent on (for SEND payments) or the date this payment should arrive by (for LAND payments)

execution.margin

integer

number of hours before execution date, this payment may be sent if funds exist

final

object

Properties describing the finalization of this payment details

final.is_final

boolean

is the amount final

final.expected

string

date-time

If the amount is not final yet, when is the final amount expected

id

string

The unique id of the payment

info

object

Extra info on the payment and its execution

info.status

PaymentRequestStatusEnum

PENDING, COMPLETED, FAILED, PROCESSING, PARTIAL, CANCELLED, PROCESSED

The current payment status

info.credit

object

If the payment has been processed, holds the amount credited

info.credit.currency

string

/^[A-Z]{3}$/

the 3 letter ISO currency code this payment will be credited in

info.credit.amount

number

The amount credited

info.funding

object

If the payment has not been processed yet, holds information about the funding requirments

info.funding.currency

string

/^[A-Z]{3}$/

the 3 letter ISO currency code this amount is to be funded in

info.funding.amount

number

The amount required to fund

info.funding.date

string

date-time

The date the funding amount must arrive in the wallet by for this payment to execute on time

info.debit

object

The amount to be debited to wallet

info.debit.currency

string

/^[A-Z]{3}$/

the 3 letter ISO currency code this payment will be debited in

info.debit.amount

number

The amount debited

info.rate

number

FX rate applied to this payment (when cross currency)

info.fees

number

Total amount (in debiting currency) of the debited amount collected as a transactional fee

purpose

string

/^[A-Z]{4}$/

the purpose of the payment as a 4 letter iso-20022 code. see: <External code sets | ISO20022

source

PaymentRequestMethodEntity

source method

source.id

string

the id of the entity

source.type

string

the type of the entity

target

object

target.type

string

the type of the entity

target.id

string

type

string

payment

entity type (payment)

user_tags

object

A set of key/value pairs to tag the payment with

Request Example

POST /payments/payments
{
   "target": {
      "id": "1"
   },
   "source": {
      "id": "1573c466-53ba-46e7-a7f2-b6d49c79716b"
   },
   "amount": {
      "type": "LAND",
      "amount": 7000
   },
   "execution": {
      "date": "2024-03-02T09:09:51.508859936Z"
   },
   "final": {
      "is_final": true
   },
   "approved": true
}

Response Examples

{
   "id": "NaxRjIDrRueABiPN-VSkOg",
   "purpose": "SALA",
   "source": {
      "id": "1573c466-53ba-46e7-a7f2-b6d49c79716b",
      "type": "group"
   },
   "target": {
      "type": "contact",
      "id": "1"
   },
   "info": {
      "funding": {
         "currency": "USD",
         "amount": 7000
      },
      "status": "PENDING",
      "credit": {
         "currency": "USD",
         "amount": 7000
      },
      "fees": 0
   },
   "amount": {
      "type": "LAND",
      "amount": 7000
   },
   "execution": {
      "date": "2024-03-02T09:09:51Z"
   },
   "final": {
      "is_final": true
   },
   "attachments": [],
   "approved": true,
   "user_tags": {}
}

Last updated