Submit a batch of payments using a payment provider or subscription
Less than to read
To submit a batch of payments to a Payments Out Service payment provider, or a payment provider via a subscription, send a POST request with the following headers and body.
Payments Out Service retains a submitted batch of payments for 365 days. After that period, the batch is automatically deleted.
Headers
POST /v3/batchpayments HTTP/1.1
Host: api-payout.sage.com
x-idempotency-key: {idempotency key}
Content-Type: application/json
Authorization: Bearer {access token}
x-fapi-interaction-id: {UUID}
Where:
{idempotency key}is an arbitrary unique value such as a UUID, serving as an idempotency key. Your request is processed once per idempotency key, which remains valid for 2 weeks.- Bearer
{access token}is the authorisation string for your request, where{access token}is a valid token created using the companyId of the company you want to submit a batch of payments for. {UUID}is a Universally Unique Identifier to write into logs. This value is used to debug your application’s integration with Payments Out Service. Use a new UUID for each request. UUIDs must conform to RFC 4122.
For more information about this REST resource and its parameters, go to the Consumer API reference.
Body
The body must contain JSON-formatted data, and include the following fields:
externalId- Either
providerIdorsubscriptionId
Consider the following limitations:
-
The payments must satisfy the provider’s rules. See the Get definitions of supported electronic payments providers and Understand provider rules guides for more information.
-
The maximum number of payments in a batch is 2000. The number of payments supported by a provider can be less than 2000. This number is defined by
maximumPaymentCountwithin the provider’s definition file. -
The maximum size of the request body that includes the batch of payments cannot exceed 5Mb.
Example body
The following example shows a batch to be submitted to a payment provider. To submit a batch using a subscription instead, substitute providerId with subscriptionId.
The payment in this batch specifies 1 invoice. You should not submit more than 2000 invoices in any 1 batch of payments.
{
"externalId": "{UUID}",
"providerId": "{ProviderId}",
"userIdentification": {
"name": "Richard",
"identification": "RPC925723",
"userIdentificationSystem": "CloudId"
},
"requestedExecutionDateTime": "2019-01-31T00:00:00Z",
"additionalData": "{\"apcaNumber\" : \"AN517546\"}",
"appId": "sage.intacct",
"localInstrument": "BACS",
"debtorAgent": {
"schemeName": "BICFI",
"identification": "123456"
},
"debtorAccount": {
"schemeName": "SortCodeAccountNumber",
"identification": "12345612345678",
"name": "Top Toys Store",
"secondaryIdentification": "ROLENO215324"
},
"payments": [
{
"externalId": "{UUID}",
"localInstrument": "BACS",
"requestedExecutionDateTime": "2019-01-31T00:00:00Z",
"additionalData": "{\"apcaNumber\" : \"AN517546\"}",
"instructedAmount": {
"amount": "1421.54",
"currency": "USD"
},
"debtorAgent": {
"schemeName": "BICFI",
"identification": "123456"
},
"debtorAccount": {
"schemeName": "SortCodeAccountNumber",
"identification": "12345612345678",
"name": "Top Toys Store",
"secondaryIdentification": "ROLENO215324"
},
"creditor": {
"name": "Fred Blogs",
"postalAddress": {
"addressLine1": "Flat 5",
"addressLine2": "57 Whitwell Acres",
"addressLine3": "Pity Me",
"addressLine4": "Durham City",
"postalCode": "DH12YJ",
"countrySubdivision": "County Durham",
"countryCode": "GB",
"country": "GB"
},
"contactEmail": "[email protected]",
"remittanceEmail": "[email protected]",
"phoneNumber": "44 7781 736 883"
},
"creditorAgent": {
"schemeName": "BICFI",
"identification": "123456"
},
"creditorAccount": {
"schemeName": "SortCodeAccountNumber",
"identification": "12345612345678",
"name": "Jane Blogs Corp.",
"secondaryIdentification": "ROLLNO151624"
},
"remittanceInformation": {
"unstructured": "Internal ops code 5120101",
"reference": "FRESCO-101",
"invoices": [
{
"invoiceNumber": "10001",
"invoiceDate": "2019-01-31T08:38:32Z",
"taxAmount": "20.00",
"discountAmount": "2.50",
"grossAmount": "117.50",
"paidAmount": "117.50",
"description": "Rent"
}
]
},
"risk": {
"paymentContextCode": "BillPayment"
}
}
]
}
Where:
{UUID}is a unique value such as a UUID assigned by the submitting application to unambiguously identify the batch of payments.{ProviderId}or{SubscriptionId}identifies the payment provider or the subscription the batch is to be posted to.
Example response
Once your batch of payments is submitted, its status is set to Received.
Use the URL in the self element to check the status of the batch. For details, go to the Check batch status guide.
Consuming applications need to take action on receipt of the ‘AwaitingAuthorisation’ status. This response contains a link for authorisation of the payments through the provider. Until the payments are authorised (and sufficient funds are available), they cannot be made.
Some providers send webhooks to inform the consuming application of subscription status changes. To receive webhooks, the consuming application must implement an endpoint that conforms to the Consumer Webhooks API. You must notify Sage Network Platform of this endpoint.
The following example shows a response where providerId was specified in the POST. Had the POST used subscriptionId, that would be returned instead.
{
"data": {
"externalId": "8369cf0c-a758-4457-9f3b-f6faaf7a829e",
"providerId": "{ProviderId}",
"userIdentification": {
"name": "Richard",
"identification": "RPC925723",
"userIdentificationSystem": "CloudId"
},
"requestedExecutionDateTime": "2019-01-31T00:00:00Z",
"additionalData": "{\"apcaNumber\" : \"AN517546\"}",
"appId": "sage.intacct",
"localInstrument": "BACS",
"debtorAgent": {
"schemeName": "BICFI",
"identification": "123456"
},
"debtorAccount": {
"schemeName": "SortCodeAccountNumber",
"identification": "12345612345678",
"name": "Top Toys Store",
"secondaryIdentification": "ROLENO215324"
},
"payments": [
{
"externalId": "8369cf0c-a758-4457-9f3b-f6faaf7a829e",
"localInstrument": "BACS",
"requestedExecutionDateTime": "2019-01-31T00:00:00Z",
"additionalData": "{\"apcaNumber\" : \"AN517546\"}",
"instructedAmount": {
"amount": "1421.54",
"currency": "USD"
},
"debtorAgent": {
"schemeName": "BICFI",
"identification": "123456"
},
"debtorAccount": {
"schemeName": "SortCodeAccountNumber",
"identification": "12345612345678",
"name": "Top Toys Store",
"secondaryIdentification": "ROLLNO215324"
},
"creditor": {
"name": "Fred Blogs",
"postalAddress": {
"addressLine1": "Flat 5",
"addressLine2": "57 Whitwell Acres",
"addressLine3": "Pity Me",
"addressLine4": "Durham City",
"postalCode": "DH12YJ",
"countrySubdivision": "County Durham",
"countryCode": "GB",
"country": "GB"
},
"contactEmail": "[email protected]",
"remittanceEmail": "[email protected]",
"phoneNumber": "44 7781 736 883"
},
"creditorAgent": {
"schemeName": "BICFI",
"identification": "123456"
},
"creditorAccount": {
"schemeName": "SortCodeAccountNumber",
"identification": "12345612345678",
"name": "Jane Blogs Corp.",
"secondaryIdentification": "ROLENO151624"
},
"remittanceInformation": {
"unstructured": "Internal ops code 5120101",
"reference": "FRESCO-101",
"invoices": [
{
"invoiceNumber": "10001",
"invoiceDate": "2019-01-31T08:38:32Z",
"taxAmount": "20.00",
"discountAmount": "2.50",
"grossAmount": "117.50",
"paidAmount": "117.50",
"description": "Rent"
}
]
},
"risk": {
"paymentContextCode": "BillPayment"
},
"paymentId": "035a96a0-af9a-4096-996b-a5f3aeac0746-00000",
"creationDateTime": "2019-01-31T08:38:32Z",
"status": "AwaitingAuthorisation",
"extendedStatus": "string",
"extendedStatusDetail": "string"
}
],
"batchId": "2b09f462-442b-4d8c-97ca-8f5b9046bcdf",
"status": "AwaitingAuthorisation",
"extendedStatus": "string",
"extendedStatusDetail": "string"
},
"links": {
"self": "https://xyz-api-payout.sage.com/v3/batchpayments/4a42ab7a-1f30-44e2-b27c-4afdba63a161",
"authorise": "https://provider.com/abcde12345"
}
}