Create a subscription to a payment provider

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.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 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. This data should be passed in the POST’s additionalData field. It should be a JSON-formatted string.

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 a subscription with a provider.

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