Create Payment Instruction
The API creates payment Instructions and enables you to transfer funds to the registered beneficiary.
POST /payments/payments
Body parameters - Request
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
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