To create a new standing order, you will need to send an HTTP POST request to the following endpoint. Note that a merchant must have first enabled standing orders in the TrustistTransfer app before placing any standing orders and a message will be returned to the create request if this has not yet happened or if their access token has expired.
POST https://<api-host>/v1/standingorders
Replace `<api-host>` with the appropriate API host URL, either `https://api-sandbox.trustistecommerce.com` for the sandbox environment or `https://api.trustistecommerce.com` for the production environment.
Headers:
– `Content-Type`: `application/json`
– `Authorization`: Hawk authentication header (generated using your client ID, private key, and other Hawk authentication parameters)
Payload:
The request body should be a JSON object containing the following fields:
– `amount`: Each payment amount as a decimal value (e.g., 12.34)
– ‘startDate’: The date the first payment is to be made, should be no earlier than tomorrow and in the format ‘yyyy-MM-dd’
– ‘frequency’: How often the standing order should be taken (Weekly, Monthly, Annually)
– ‘numberOfPayments’ – An integer to represent how many payments should be taken before the standing order ends or zero (0) to represent a standing order that is set to never expire
– `reference`: A string containing a unique reference for the standing order (e.g., “Order 1234”)
– `returnUrl`: The URL to redirect the user to after the payment is completed (e.g., “https://www.example.com?orderId=1234”)
– `cancelUrl`: The URL to redirect the user to if they cancel out of the payment process
– ‘description’: A human-readable text description for the transaction (optional)
– ‘payerName’: The end customer’s name
– ‘payerBusinessName’: The business name for the end customer (optional)
Example request:
POST https://api-sandbox.trustistecommerce.com/v1/standingorders
Content-Type: application/json
Authorization: Hawk id=”your-client-id”, ts=”1618886397″, nonce=”a_random_nonce”, hash=”generated_request_hash”, ext=”hawk.1.header”, mac=”generated_mac”
{
“amount”: 12.34,
“reference”: “Order_1234”,
“returnUrl”: “https://www.example.com?orderId=1234”,
“frequency”: “Weekly”,
“numberOfPayments”: “12”,
“startDate”: “2024-03-18”,
“payerName”: “Mr Customer”,
}
Response:
The API will respond with a JSON object containing the following fields:
– `id`: A unique identifier for the created standing order, used later to return the result after the customer has completed their journey
– `payLink`: A URL to redirect the customer to complete the standing order If successful, the response will have a 200 OK status code. In case of an error, the API will return an appropriate error status code and a message describing the issue.
