Create a subscription to a payment provider
Less than to read
When you submit a batch of payments you must specify the providerId of the provider you want to process it.
For some providers, you need to create an account with them before making a payment. This is a subscription. For these providers, use subscriptionId in place of providerId when submitting payment requests.
To create a subscription to a Payments Out Service payment provider, which can generate a batch of payments, send a POST request with the following headers:
POST /v3/subscriptions/organisations/{organisationId}/subscriptions HTTP/1.1
Host: api-payout.sage.com
Content-Type: application/json
x-application: {app name}
x-idempotency-key: {Idempotency UUID}
x-api-key: {api key}
Authorization: Bearer {access token}
Where:
-
{app name}is the name of an application supported by the Payments Out Service, in an acceptable format. For example, sage.intacct -
{api key}is the API key for the Consumer API. -
{Idempotency UUID}is a random Universally Unique Identifier which must be unique for each distinct request. If you need to re-submit the same request without the risk of creating a duplicate then use the same idempotency key. UUIDs must conform to RFC 4122. -
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 to.
For more information about this REST resource and its parameters, go to the Consumer API reference.
Body
-
The subscription payload must satisfy the provider’s rules. Go to the Get definitions of supported electronic payments providers and Understand provider rules guides for more information.
-
The
$.data.providerIdelement in the JSON request is the providerId of the provider you want to create a subscription to. -
The
$.data.additionalDataelement in the JSON request is a string containing JSON-formatted data. This is required by the provider.
Example response
This response contains details of a sample subscription. Use the URL in the self element to check the status of the submitted subscription.
Consuming applications need to take action on receipt of status ‘AwaitingAuthorisation’. This response contains a link to set up and authorise the subscription with the provider. This will involve either signing up, or signing in to an account with the provider.
Until the subscription returns an ‘Active’ status, the user will not be able to use it. This includes using it for creating debtor accounts, creditors or payments. For more information, go to Retrieve subscription details.
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. Sage Network Platform must be aware of this endpoint.
Take a look at an example response.
Provider-specific additionalData examples
Providers can request additionalData values to allow pre-configuration on receipt of the subscription request.
In the CSI section, you can see the data that each provider requests. This data should be passed in the POST’s additionalData field. It should be a JSON-formatted string.
CSI
When creating a subscription, the request to CSI can include additional information. If the submitting software has stored this information, it can pass through in the request. This minimises the setup the user needs to complete in the CSI portal when authorising the subscription.
The following example shows the structure of additionalData. The descriptions of individual fields follow. Although this data is optional, it will improve the customer experience when setting up in CSI.
{
"company":{
"legalName":"Test Company 2",
"dbaName":"Test Company 2",
"website":"company.com",
"taxId":"123456789",
"yearsInBusiness":5,
"stateOfFormation":"OH",
"naicsCode":"1234",
"sourceOfIncome":"source",
"businessDescription":"IT",
"numberOfOwners": 2,
"subscriptionID":"123456789"
},
"companyAddress":{
"addressLine1":"1234 Main St",
"city":"Cincinnati",
"state":"OH",
"zip":"45039",
"countryCode":"US"
},
"companyPrimaryContact":{
"name":"John Smith",
"phone":"555-555-5555",
"phoneType":"mobile",
"email":"[email protected]"
},
"companyControlPerson":{
"name":"Bob Smith",
"phone":"555-555-5555",
"phoneType":"mobile",
"email":"[email protected]"
},
"companyOwners":[
{
"legalName":"John Smith",
"title":"CEO",
"dateOfBirth":"04/02/1986",
"homeAddress":{
"addressLine1":"1234 Main St",
"city":"Cincinnati",
"state":"OH",
"zip":"45039",
"countryCode":"US"
},
"last4SSN":"0492",
"percentOwnership":50,
"phone":"555-555-5555",
"phoneType":"mobile",
"idType":"",
"dlNumber":"",
"stateOfIssuance":"OH",
"passportNumber":"",
"countryOfIssuance":"US",
"expirationDateOfId":""
},
{
"legalName":"John Smith",
"title":"CEO",
"dateOfBirth":"04/02/1986",
"homeAddress":{
"addressLine1":"1234 Main St",
"city":"Cincinnati",
"state":"OH",
"zip":"45039",
"countryCode":"US"
},
"last4SSN":"0492",
"percentOwnership":50,
"phone":"555-555-5555",
"phoneType":"mobile",
"idType":"",
"dlNumber":"",
"stateOfIssuance":"OH",
"passportNumber":"",
"countryOfIssuance":"US",
"expirationDateOfId":""
}
]
}
| company object | |
|---|---|
| legalName | The business’s legal name |
| dbaName | The company’s ‘doing business as’ name. In the UK this is known as ‘trading as’ |
| website | The business website URL |
| taxId | The business’s tax ID |
| yearsInBusiness | The number of years the business has been formed |
| stateOfFormation | The state in which the business was formed |
| naicsCode | The North American Industry Classification code |
| sourceOfIncome | The origin and means of transfer of monies that are accepted for the account. Funding sources can include but are not limited to: business income, retained earnings, debt capital, equity capital, inheritance, divorce settlement. |
| businessDescription | The business description |
| numberOfOwners | The number of people who share ownership of the business – includes people that own 25 percent or more |
| companyAddress object | |
|---|---|
| addresssLine1 | The first line of the business address |
| city | The city of the business |
| state | The state the business resides in |
| zip | The business zip code |
| countryCode | The country code for this address (use 2-character ISO country code) |
| companyPrimaryContact object | |
|---|---|
| name | The primary contact’s name |
| phone | The primary contact’s phone number |
| phoneType | The primary contact’s phone type e.g. mobile |
| The primary contact’s email address |
| companyControlPerson object | This is a person that has significant responsibility for running the business. |
|---|---|
| name | The person’s name |
| phone | The person’s phone number |
| phoneType | The phone type e.g. mobile |
| The person’s email address |
| companyOwners array object | This object is unlikely to be held within the application, so would usually be entered via CSI’s UI. |
|---|---|
| legalName | The owner’s name |
| title | The owner’s title e.g. CEO |
| dateOfBirth | The owner’s date of birth |
| homeAddress | The owner’s home address |
| last4ssn | The last 4 digits of the owner’s social security number |
| percentOwnership | The percentage of the business that this person owns |
| phone | The owner’s phone number |
| phoneType | The phone type e.g. mobile |
| idType | e.g. Driver’s license, passport, government-issued ID |
| dlNumber | The number from the ID above |
| stateOfIssuance | The state in which the ID was issued |
| expirationOfId | The expiry date of the ID |
| companyOwners homeAddress object | |
|---|---|
| addresssLine1 | The first line of the owner’s address |
| city | The city the owner resides in |
| state | The state the owner resides in |
| zip | The owner’s zip code |
| countryCode | The country code for this address (use 2-character ISO country code) |