Bulk Import Payment Instructions

The API is utilized to send bulk payments to authorized beneficiaries.

POST /payments/payments/import

Body Parameters - Request

Name	Type	Format / Values	Description	Required
items	array	object	List of items to import
items[].id	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
items[].description	string		The remittence info to send as part of the payment
items[].signature	string
items[].purpose	string	/^([A-Z]{4})$/	the purpose of the payment as a 4 letter iso-20022 code. see: <External code sets | ISO20022
items[].source	object			Yes
items[].source.type	string	group	type of source (must be group)
items[].source.id	string			Yes
items[].target	object			Yes
items[].target.type	string	contact
items[].target.id	string		The id of the target entity (beneficiary)	Yes
items[].approved	boolean		Set to true to mark the payment as approved and ready to be executed
items[].amount	object		Specifies the amount of the payment	Yes
items[].amount.type	string	LAND, SEND	Does the amount refer to the amount credited (LAND), or the amount debited (SEND)
items[].amount.amount	number		The amount (up to 3 decimal points)	Yes
items[].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
items[].execution	object		specifies info for the executing date	Yes
items[].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)
items[].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)	Yes
items[].execution.margin	integer		number of hours before execution date, this payment may be sent if funds exist
items[].final	object		Properties describing the finalization of this payment details
items[].final.is_final	boolean		is the amount final
items[].final.expected	string	date-time	If the amount is not final yet, when is the final amount expected
items[].attachments	array	object	List of files to attach to the payment
items[].attachments[]	object
items[].attachments[].id	string		a unique id to give the attachment
items[].attachments[].title	string		A title to give the attachment
items[].attachments[].url	string		a url link to the attachment	Yes
items[].user_tags	object		A set of key/value pairs to tag the payment with

Body Parameters - Response

Name	Type	Format / Values	Description
started_at	string	date-time	The date the job started
total	integer		total number of payments in job
processing	integer		total number of payments being processed
processed	integer		total number of payments successfully processed
failed	integer		total number of payments failed
status	string	QUEUED, DONE	status of job
progress	array	object	list of completed items and their status
progress[]	object
progress[].id	string		id or payment
progress[].status	string	SUCCESS, FAILED	status of payment creation
progress[].row	string		index of item in job
progress[].error	object		error object if any

Request Example

POST /payments/payments/import
{
   "items": [
      {
         "target": {
            "id": "20"
         },
         "source": {
            "id": "ba1acd2e-2133-442f-acc4-a74b1b760a04"
         },
         "amount": {
            "type": "LAND",
            "amount": 5000
         },
         "execution": {
            "date": "2024-03-05T09:09:51.509545358Z"
         },
         "final": {
            "is_final": true
         }
      },
      {
         "target": {
            "id": "16"
         },
         "source": {
            "id": "ba1acd2e-2133-442f-acc4-a74b1b760a04"
         },
         "amount": {
            "type": "LAND",
            "amount": 5000
         },
         "execution": {
            "date": "2024-03-02T09:09:51.509426624Z"
         },
         "final": {
            "is_final": true
         }
      }
   ]
}

Response Examples

202 - Accepted

{
   "processed": 0,
   "total": 2,
   "job_id": "76I_SRe9ToeDwSExCGrgtA",
   "started_at": "2024-03-05T21:49:22.444288513Z",
   "processing": 2,
   "progress": [],
   "failed": 0,
   "status": "QUEUED"
}

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
}