Skip to content
Developerhome

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 rules as defined by the provider. Go to the Get definitions of supported electronic payments providers and Understand provider rules guides for more information.

  • The $.data.providerId element in the JSON request is the providerId of the provider you want to create a subscription to.

  • The $.data.additionalData element 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 a status of ‘Active’, the user will not be able to use it. This includes using it for creating debtor accounts, creditors or payments. For more information, see 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. Service Fabric 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
email 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
email 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)