To create a new payment, you will need to send an HTTP POST request to the following endpoint:
POST https://<api-host>/v1/payments
Replace <api-host> with the appropriate API host URL:
- Sandbox: https://api-sandbox.trustistecommerce.com
- Production: https://api.trustistecommerce.com
Headers #
- Content-Type: application/json
- Authorization: HMAC-SHA256 authentication header (generated using your client ID, private key, and other HMAC parameters)
- x-tr-date: Current UTC timestamp in RFC1123 format
- x-tr-clientid: Your API client ID
- x-tr-content-sha256: SHA256 hash of the request body
Request Payload #
The request body should be a JSON object containing the following fields:
Required Fields #
- amount: The payment amount as a decimal value (e.g., 12.34)
- reference: A string containing a unique reference for the payment (e.g., “Order_1234”)
Optional Fields #
- returnUrl: The URL to redirect the user to after successful payment completion
- cancelUrl: The URL to redirect the user to if they cancel the payment process (defaults to returnUrl if not provided)
- description: A human-readable text description for the transaction
- customerDetails: A single-line text entry to identify the customer
- payerEmail: Email address of the payer
- logoUrl: URL to a custom logo to display during the payment process
- partnerId: Partner identifier (GUID or ShortGuid format)
- partnerReference: Partner-specific reference for the transaction
- workflow: An object that provides parameters to determine the course of the payer journey (see Workflow section below)
Workflow #
The workflow object determines how a payer moves through their payment journey. The available modes are Default, SkipIntro, RemoteOnly, and MOTO.
Default #
The standard payment flow that guides the payer through the full Trustist payment experience, including introductory screens and payment method selection.
SkipIntro #
Forwards the payer directly to the payment process, bypassing introductory screens. This mode only works if cards are not enabled on the merchant account, as it denies the opportunity to choose between Open Banking and card payments. It requires that the merchant software explains sufficiently what is about to happen, as the payer will be immediately taken into the payment process.
RemoteOnly #
Forces the payer to carry out the transaction on their mobile device, made possible by scanning a QR code if not already on a mobile device. This mode is ideal for in-person transactions where the merchant wants to ensure the customer uses their own device for payment entry.
MOTO #
Mail Order/Telephone Order mode enables merchants to process card payments on behalf of customers over the phone or via mail order. In this mode:
- The merchant collects payment details directly from the customer
- Payment is processed through a secure MOTO form at /moto/{identifier} URLs
- Supports both manual capture (for pre-authorization) and automatic capture workflows
- Requires additional approval from the payment processor
- Designed for scenarios where the customer is not present to enter their own payment details
Additional Workflow Properties #
Beyond the mode, the workflow object supports additional behavioral controls:
- suppressMerchantEmails: Prevents notification emails being sent to the merchant
- suppressPayerEmails: Prevents notification emails being sent to the payer
- suppressRetryOnFailure: When enabled, failed payments redirect the customer back to the merchant’s return URL instead of offering a retry option – see https://trustisttransfer.com/docs/payment-retry-suppression/
Return URLs #
Return URLs are now optional for all workflow modes. While traditionally required for web-based integrations, they may not be needed when payments are created programmatically via API without a web interface. When provided, return URLs enable seamless redirection back to the merchant’s website after payment completion.
Example Request #
POST https://api-sandbox.trustistecommerce.com/v1/payments
Content-Type: application/json
Authorization: HMAC-SHA256 SignedHeaders=x-tr-date;x-tr-clientid;host;x-tr-content-sha256&Signature=<generated_signature>
x-tr-date: Mon, 19 Apr 2021 15:26:37 GMT
x-tr-clientid: your-client-id
x-tr-content-sha256: <content_hash>
{
“amount”: 12.34,
“reference”: “Order_1234”,
“returnUrl”: “https://www.example.com?orderId=1234”,
“description”: “Product purchase”,
“customerDetails”: “John Smith”,
“payerEmail”: “john@example.com”,
“workflow”: {
“mode”: “Default”,
“suppressMerchantEmails”: false,
“suppressPayerEmails”: false,
“suppressRetryOnFailure”: false
}
}
Response #
The API will respond with a JSON object containing the following fields:
- id: A unique identifier for the created payment
- payLink: A URL to redirect the customer to complete the payment
Success Response #
{
“id”: “encrypted_payment_identifier”,
“payLink”: “https://pay.trustist.com/pay/encrypted_payment_identifier”
}
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.
Authentication #
The TrustistEcommerce API uses HMAC-SHA256 authentication. You’ll need:
- A client ID (provided when you register for API access)
- A private key (provided when you register for API access)
The authentication process involves signing your request with these credentials and including specific headers as shown in the example above.
