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
id	Url Path	string		A unique id for this payment (if none provided, an id will be assigned). Using an existing payment id will update the pending payment
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
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

201 - Created

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

400 - Bad Request

{
  "error": "bad_request",
  "description": "Validation errors: {\"type\":\"INDIVIDUAL\",\"id\":\"5SYjAkHqXHW0Z2cqBRW4JAAA\",\"cou... at root failed with \"Missing property org_id\"",
  "error_code": 400
}