API docs by Redocly

Payments API (4.3.0)

Download OpenAPI specification:Download

Welcome to the documentation for the Truevo Payments API. These APIs provide a unified interface to securely accept and process payment transactions. Using this API, you can perform various payment operations through a uniform, secure and reliable interface. All new integrations are supported with modern REST APIs using the JSON standard for data payloads. Each operation is implemented through a multistep process that supports reliable rapid communication. All operations are performed using a two-step approach. The first step involves requesting a transaction to be performed. The second step is to ask for the outcome of that request. For example, you may request an authorisation to be performed, providing the card details and transaction amount. The system will acknowledge this request. Following this, you will request the information required to determine whether the transaction was successfully authorised. By using a two-step approach, no long-running connection is required. Truevo will immediately respond with an acknowledgement allowing both parties to continue their operations. This limits failures due to poor network conditions; allows for retry and recoverability, and facilitates better resource usage.

Payments

Payment Services. This section contains the direct Truevo payment endpoints.

Authorise a Payment

Create a new payment and request an authorization hold. This amount can be captured in a later request. If not captured, delayed cancellation will occur.

Authorizations:
TokenAuthorizer
header Parameters
idempotencyKey
required
string

Idempotency allows a request to be retried multiple times without the operation being performed more than once. A unique identifier must be provided in this parameter to identify the request and prevent duplicate processing. It is recommended that you utilize a GUID or similar mechanism.

authorization
required
string

Bearer token used to authenticate the request.

Request Body schema: application/json
required
object (transaction)

Details specific to the transaction being processed.

required
object (merchant)

Details specific to the merchant processing the transaction.

required
object

Details related to the card.

object (initiateSecureEcommerce)

Details required to initiate a secure ecommerce payment

object (secureEcommerce)

Details required for a secure ecommerce payment

object (recurringData)

Details related to Recurring transactions.

object (terminal)

Details specific to the card terminal

object (customer)

Details specific to the customer

Array of objects (additionalData)

Additional data can be provided in this field. This may be required by Truevo to support certain types of transactions or operations.

object (industry)

Additional fields for industry.

Responses

Request samples

Content type
application/json
{
  • "transaction": {
    },
  • "merchant": {
    },
  • "card": {
    },
  • "initiateSecureEcommerce": {
    },
  • "secureEcommerce": {
    },
  • "recurring": {
    },
  • "terminal": {
    },
  • "customer": {
    },
  • "additionalData": [
    ],
  • "industry": {
    }
}

Response samples

Content type
application/json
{
  • "transactionUniqueIdentifier": "fac3ce40-0c4d-45f5-964a-af46f359fe71",
  • "merchantReference": "test-merchant-reference",
  • "retrievalReferenceNumber": "000001707706",
  • "idempotencyKey": "af46f359fe71",
  • "timestampSubmitted": "2021-09-22T09:54:07",
  • "amount": {
    },
  • "additionalData": [
    ],
  • "outcome": {
    },
  • "merchantAdviceCode": "1"
}

Process a Sale

Process a single request for both authorisation and capture of a payment amount. This operation is usually performed when a service or product is provided at the time of payment.

Authorizations:
TokenAuthorizer
header Parameters
idempotencyKey
required
string

Idempotency allows a request to be retried multiple times without the operation being performed more than once. A unique identifier must be provided in this parameter to identify the request and prevent duplicate processing. It is recommended that you utilize a GUID or similar mechanism.

authorization
required
string

Bearer token used to authenticate the request.

Request Body schema: application/json
required
object (transaction)

Details specific to the transaction being processed.

required
object (merchant)

Details specific to the merchant processing the transaction.

required
object

Details related to the card.

object (initiateSecureEcommerce)

Details required to initiate a secure ecommerce payment

object (secureEcommerce)

Details required for a secure ecommerce payment

object (recurringData)

Details related to Recurring transactions.

object (terminal)

Details specific to the card terminal

object (customer)

Details specific to the customer

Array of objects (additionalData)

Additional data can be provided in this field. This may be required by Truevo to support certain types of transactions or operations.

object (industry)

Additional fields for industry.

Responses

Request samples

Content type
application/json
{
  • "transaction": {
    },
  • "merchant": {
    },
  • "card": {
    },
  • "initiateSecureEcommerce": {
    },
  • "secureEcommerce": {
    },
  • "recurring": {
    },
  • "terminal": {
    },
  • "customer": {
    },
  • "additionalData": [
    ],
  • "industry": {
    }
}

Response samples

Content type
application/json
{
  • "transactionUniqueIdentifier": "fac3ce40-0c4d-45f5-964a-af46f359fe71",
  • "merchantReference": "test-merchant-reference",
  • "retrievalReferenceNumber": "000001707706",
  • "idempotencyKey": "af46f359fe71",
  • "timestampSubmitted": "2021-09-22T09:54:07",
  • "amount": {
    },
  • "additionalData": [
    ],
  • "outcome": {
    },
  • "merchantAdviceCode": "1"
}

Capture a Payment

Provide an authorised transaction and request capture for the specified amount. This is not necessary in the case of a sale transaction that is automatically captured.

Authorizations:
TokenAuthorizer
header Parameters
idempotencyKey
required
string

Idempotency allows a request to be retried multiple times without the operation being performed more than once. A unique identifier must be provided in this parameter to identify the request and prevent duplicate processing. It is recommended that you utilize a GUID or similar mechanism.

authorization
required
string

Bearer token used to authenticate the request.

Request Body schema: application/json
required
object (referenceTransactionWithRrn)

Details specific to the transaction being processed.

required
object (merchantDetails)

Details specific to the merchant in the Truevo System.

object (customer)

Details specific to the customer

Array of objects (additionalData)

Additional data can be provided in this field. This may be required by Truevo to support certain types of transactions or operations.

Responses

Request samples

Content type
application/json
{
  • "transaction": {
    },
  • "merchant": {
    },
  • "customer": {
    },
  • "additionalData": [
    ]
}

Response samples

Content type
application/json
{
  • "transactionUniqueIdentifier": "fac3ce40-0c4d-45f5-964a-af46f359fe71",
  • "merchantReference": "test-merchant-reference",
  • "retrievalReferenceNumber": "000001707706",
  • "idempotencyKey": "af46f359fe71",
  • "timestampSubmitted": "2021-09-22T09:54:07",
  • "amount": {
    },
  • "additionalData": [
    ],
  • "outcome": {
    },
  • "merchantAdviceCode": "1"
}

Reverse a Transaction

Void the transaction and reverse it's effects. This operation can only be performed until a cut-off point for the transaction.

Authorizations:
TokenAuthorizer
header Parameters
idempotencyKey
required
string

Idempotency allows a request to be retried multiple times without the operation being performed more than once. A unique identifier must be provided in this parameter to identify the request and prevent duplicate processing. It is recommended that you utilize a GUID or similar mechanism.

authorization
required
string

Bearer token used to authenticate the request.

Request Body schema: application/json
required
object (reverseTransaction)

Details specific to the transaction being processed.

required
object (merchantDetails)

Details specific to the merchant in the Truevo System.

object (customer)

Details specific to the customer

Array of objects (additionalData)

Additional data can be provided in this field. This may be required by Truevo to support certain types of transactions or operations.

Responses

Request samples

Content type
application/json
{
  • "transaction": {
    },
  • "merchant": {
    },
  • "customer": {
    },
  • "additionalData": [
    ]
}

Response samples

Content type
application/json
{
  • "transactionUniqueIdentifier": "fac3ce40-0c4d-45f5-964a-af46f359fe71",
  • "merchantReference": "test-merchant-reference",
  • "retrievalReferenceNumber": "000001707706",
  • "idempotencyKey": "af46f359fe71",
  • "timestampSubmitted": "2021-09-22T09:54:07",
  • "amount": {
    },
  • "additionalData": [
    ],
  • "outcome": {
    },
  • "merchantAdviceCode": "1"
}

Process a Linked Refund

Process a single request for a refund of a linked transaction.

Authorizations:
TokenAuthorizer
header Parameters
idempotencyKey
required
string

Idempotency allows a request to be retried multiple times without the operation being performed more than once. A unique identifier must be provided in this parameter to identify the request and prevent duplicate processing. It is recommended that you utilize a GUID or similar mechanism.

authorization
required
string

Bearer token used to authenticate the request.

Request Body schema: application/json
required
object (referenceTransaction)

Details specific to the transaction being processed.

required
object (merchantDetails)

Details specific to the merchant in the Truevo System.

object (customer)

Details specific to the customer

Array of objects (additionalData)

Additional data can be provided in this field. This may be required by Truevo to support certain types of transactions or operations.

Responses

Request samples

Content type
application/json
{
  • "transaction": {
    },
  • "merchant": {
    },
  • "customer": {
    },
  • "additionalData": [
    ]
}

Response samples

Content type
application/json
{
  • "transactionUniqueIdentifier": "fac3ce40-0c4d-45f5-964a-af46f359fe71",
  • "merchantReference": "test-merchant-reference",
  • "retrievalReferenceNumber": "000001707706",
  • "idempotencyKey": "af46f359fe71",
  • "timestampSubmitted": "2021-09-22T09:54:07",
  • "amount": {
    },
  • "additionalData": [
    ],
  • "outcome": {
    },
  • "merchantAdviceCode": "1"
}

Process a Refund

Process a single request for refund.

Authorizations:
TokenAuthorizer
header Parameters
idempotencyKey
required
string

Idempotency allows a request to be retried multiple times without the operation being performed more than once. A unique identifier must be provided in this parameter to identify the request and prevent duplicate processing. It is recommended that you utilize a GUID or similar mechanism.

authorization
required
string

Bearer token used to authenticate the request.

Request Body schema: application/json
required
object (transaction)

Details specific to the transaction being processed.

required
object (merchant)

Details specific to the merchant processing the transaction.

required
object

Details related to the card.

object (terminal)

Details specific to the card terminal

object (customer)

Details specific to the customer

Array of objects (additionalData)

Additional data can be provided in this field. This may be required by Truevo to support certain types of transactions or operations.

Responses

Request samples

Content type
application/json
{
  • "transaction": {
    },
  • "merchant": {
    },
  • "card": {
    },
  • "terminal": {
    },
  • "customer": {
    },
  • "additionalData": [
    ]
}

Response samples

Content type
application/json
{
  • "transactionUniqueIdentifier": "fac3ce40-0c4d-45f5-964a-af46f359fe71",
  • "merchantReference": "test-merchant-reference",
  • "retrievalReferenceNumber": "000001707706",
  • "idempotencyKey": "af46f359fe71",
  • "timestampSubmitted": "2021-09-22T09:54:07",
  • "amount": {
    },
  • "additionalData": [
    ],
  • "outcome": {
    },
  • "merchantAdviceCode": "1"
}

Process an Original Credit Transfer

Process a single request for an original credit transfer.

Authorizations:
TokenAuthorizer
header Parameters
idempotencyKey
required
string

Idempotency allows a request to be retried multiple times without the operation being performed more than once. A unique identifier must be provided in this parameter to identify the request and prevent duplicate processing. It is recommended that you utilize a GUID or similar mechanism.

authorization
required
string

Bearer token used to authenticate the request.

Request Body schema: application/json
required
object (originalCreditTransferTransaction)

Details specific to the transaction being processed.

required
object (merchant)

Details specific to the merchant processing the transaction.

required
object

Details related to the card.

object (terminal)

Details specific to the card terminal

object (customer)

Details specific to the customer

Array of objects (additionalData)

Additional data can be provided in this field. This may be required by Truevo to support certain types of transactions or operations.

object (sender)

Details specific to the sender (OCT Money Transfer)

Responses

Request samples

Content type
application/json
{
  • "transaction": {
    },
  • "merchant": {
    },
  • "card": {
    },
  • "terminal": {
    },
  • "customer": {
    },
  • "additionalData": [
    ],
  • "sender": {
    }
}

Response samples

Content type
application/json
{
  • "transactionUniqueIdentifier": "fac3ce40-0c4d-45f5-964a-af46f359fe71",
  • "merchantReference": "test-merchant-reference",
  • "retrievalReferenceNumber": "000001707706",
  • "idempotencyKey": "af46f359fe71",
  • "timestampSubmitted": "2021-09-22T09:54:07",
  • "amount": {
    },
  • "additionalData": [
    ],
  • "outcome": {
    },
  • "merchantAdviceCode": "1"
}

Process a Linked Original Credit Transfer

Process a single request for a linked original credit transfer.

Authorizations:
TokenAuthorizer
header Parameters
idempotencyKey
required
string

Idempotency allows a request to be retried multiple times without the operation being performed more than once. A unique identifier must be provided in this parameter to identify the request and prevent duplicate processing. It is recommended that you utilize a GUID or similar mechanism.

authorization
required
string

Bearer token used to authenticate the request.

Request Body schema: application/json
required
object (referenceTransaction)

Details specific to the transaction being processed.

required
object (merchantDetails)

Details specific to the merchant in the Truevo System.

object (customer)

Details specific to the customer

Array of objects (additionalData)

Additional data can be provided in this field. This may be required by Truevo to support certain types of transactions or operations.

Responses

Request samples

Content type
application/json
{
  • "transaction": {
    },
  • "merchant": {
    },
  • "customer": {
    },
  • "additionalData": [
    ]
}

Response samples

Content type
application/json
{
  • "transactionUniqueIdentifier": "fac3ce40-0c4d-45f5-964a-af46f359fe71",
  • "merchantReference": "test-merchant-reference",
  • "retrievalReferenceNumber": "000001707706",
  • "idempotencyKey": "af46f359fe71",
  • "timestampSubmitted": "2021-09-22T09:54:07",
  • "amount": {
    },
  • "additionalData": [
    ],
  • "outcome": {
    },
  • "merchantAdviceCode": "1"
}

Automated Transaction Reversal

Void the transaction and reverse it's effects. This operation can only be performed until a cut-off point for the transaction.

Authorizations:
TokenAuthorizer
header Parameters
idempotencyKey
required
string

Idempotency allows a request to be retried multiple times without the operation being performed more than once. A unique identifier must be provided in this parameter to identify the request and prevent duplicate processing. It is recommended that you utilize a GUID or similar mechanism.

authorization
required
string

Bearer token used to authenticate the request.

Request Body schema: application/json
required
object (autoReverseTransaction)

Details specific to the transaction being processed.

required
object (merchantDetails)

Details specific to the merchant in the Truevo System.

Responses

Request samples

Content type
application/json
{
  • "transaction": {
    },
  • "merchant": {
    }
}

Response samples

Content type
application/json
{
  • "transactionUniqueIdentifier": "fac3ce40-0c4d-45f5-964a-af46f359fe71",
  • "idempotencyKey": "af46f359fe71",
  • "timestamp": "2021-09-22T09:54:07",
  • "outcome": {
    }
}

Automated Transaction Reversal using the Idempotency key.

Void the transaction and reverse it's effects. This operation can only be performed until a cut-off point for the transaction.

Authorizations:
TokenAuthorizer
header Parameters
idempotencyKey
required
string

Idempotency allows a request to be retried multiple times without the operation being performed more than once. A unique identifier must be provided in this parameter to identify the request and prevent duplicate processing. It is recommended that you utilize a GUID or similar mechanism.

authorization
required
string

Bearer token used to authenticate the request.

Request Body schema: application/json
required
object (idempotencyAutoReverseTransaction)

Details specific to the transaction being processed.

required
object (merchantDetails)

Details specific to the merchant in the Truevo System.

Responses

Request samples

Content type
application/json
{
  • "transaction": {
    },
  • "merchant": {
    }
}

Response samples

Content type
application/json
{
  • "transactionUniqueIdentifier": "fac3ce40-0c4d-45f5-964a-af46f359fe71",
  • "idempotencyKey": "af46f359fe71",
  • "timestamp": "2021-09-22T09:54:07",
  • "outcome": {
    }
}

Query Transaction Status

Retrieve the status of a previously submitted transaction. The applicable transaction identifier must be provided for the transaction in question.

Authorizations:
TokenAuthorizer
query Parameters
transactionUniqueIdentifier
required
string
Example: transactionUniqueIdentifier=fac3ce40-0c4d-45f5-964a-af46f359fe71

The unique identifier of the transaction for which you want to query.

merchantIdentifier
string
Example: merchantIdentifier=99686861

The unique identifier issued to the merchant by Truevo.

terminalIdentifier
string
Example: terminalIdentifier=99868661

The unique terminal identifier issued to the merchant by Truevo.

header Parameters
authorization
required
string

Bearer token used to authenticate the request.

Responses

Response samples

Content type
application/json
{
  • "transactionUniqueIdentifier": "fac3ce40-0c4d-45f5-964a-af46f359fe71",
  • "retrievalReferenceNumber": "000001707706",
  • "merchantReference": "test-merchant-reference",
  • "idempotencyKey": "af46f359fe71",
  • "timestampSubmitted": "2021-09-22T09:54:07",
  • "timestampProcessed": "2021-09-22T09:54:07",
  • "authCode": "ABCD1234",
  • "transactionTraceId": "0ae11d39-a3e2-4bae-bd9f-59fb63c742ef",
  • "emv": {
    },
  • "amount": {
    },
  • "additionalData": [
    ],
  • "tokenData": {
    },
  • "outcome": {
    },
  • "merchantAdviceCode": "1"
}

Continue with a previous 3DS authorized payment request

This is the second step in a sequence of steps that need to be completed in order to process a 3DS authorised payment as part of the transaction process.

Authorizations:
TokenAuthorizer
Request Body schema: application/json
transactionUniqueIdentifier
required
string

Unique identifier previously generated for a transaction.

transactionStatus
required
string (threeDSTransactionStatusEnum)
Enum: "Successful" "NotAuthenticated" "Unsuccessful" "Unactioned"

Indicate the 3ds transaction status

object (secureEcommerce)

Details required for a secure ecommerce payment

Array of objects (additionalData)

Additional data can be provided in this field. This may be required by Truevo to support certain types of transactions or operations.

Responses

Request samples

Content type
application/json
{
  • "transactionUniqueIdentifier": "string",
  • "transactionStatus": "Successful",
  • "secureEcommerce": {
    },
  • "additionalData": [
    ]
}

Response samples

Content type
application/json
{
  • "transactionUniqueIdentifier": "fac3ce40-0c4d-45f5-964a-af46f359fe71",
  • "merchantReference": "test-merchant-reference",
  • "retrievalReferenceNumber": "000001707706",
  • "idempotencyKey": "af46f359fe71",
  • "timestampSubmitted": "2021-09-22T09:54:07",
  • "amount": {
    },
  • "additionalData": [
    ],
  • "outcome": {
    },
  • "merchantAdviceCode": "1"
}

ThreeDSecure

3D-Secure Services. This section contains the endpoints for performing a standalone 3D-Secure full flow. This allows you to integrate the Truevo 3D-Secure Server in your own payment flow.

Initiate 3DS Transaction Server Flow

This endpiont will initiate the 3DS Server flow. This endpoint will recieve all data required to complete the 3DS Transaction. The endpoint will return one of 3 responses 1. Method data 2. Succesfull Completetion of 3DS Transaction 3. Challange Required.

Request Body schema: application/json

This class contains the required information needed to get the method data.

object (threeDSBrowserInformation)

This class contains all the browser information for the authentication request.

object (threeDSPurchaseInformation)

This class contains all the purchase information for the authentication request.

object (threeDSMerchantInformation)

This class contains all the merchant information for the authentication request.

object (threeDSAddress)

This class contains all the billing information for the authentication request.

object (threeDSCardholderInformation)

This class contains all the cardholder information for the authentication request.

object (threeDSAddress)

This class contains all the billing information for the authentication request.

object (threeDSAddtionalInformation)

This class contains all the addtional information for the authentication request.

deviceChannel
string
Default: "02"

This field indicates the type of channel interface being used to initiate the transaction. 01=App-Based, 02=Browser, 03=3DS Requestor Initiated (3RI)

messageCategory
string
Default: "01"

This field identifies the category of the message (Payment Authentication or Non-Payment Authentication). 01=PA (Payment Authentication), 02=NPA (Non-Payment Authentication)

notificationURL
required
string

This property specifies the URL to which the final challenge response is POSTed in a browser-based flow.

methodNotifcaitonURL
required
string

This field indicates the URL that the ACS will post back to once the ACS has gathered all data of the browser. This will be a URL on the merchant side.

Responses

Request samples

Content type
application/json
{
  • "browserInformation": {
    },
  • "purchaseInformation": {
    },
  • "merchantInformation": {
    },
  • "billingAddress": {
    },
  • "cardholderInformation": {
    },
  • "shippingAddress": {
    },
  • "addtionalInformation": {
    },
  • "deviceChannel": "02",
  • "messageCategory": "01",
  • "notificationURL": "https://google.com",
  • "methodNotifcaitonURL": "https://google.com"
}

Response samples

Content type
application/json
Example
{
  • "authenticationECI": "05",
  • "authenticationValue": "AAABBZEEBgAAAAAAAAQGAAAAAAA=",
  • "transactionStatus": "Successful",
  • "transactionUniqueIdentifier": "1f9b847b-8372-48fe-ade9-b628d3199d0e",
  • "acsOperatorID": "ACS-V210-SOUTH-BAN-2121",
  • "acsTransID": "1f9b847b-8372-48fe-ade9-b628d3199d0e",
  • "acsReferenceNumber": "3DS_LOA_ACS_MOBL_1_1",
  • "authenticationType": "03",
  • "acsChallengeMandated": "Y",
  • "dsReferenceNumber": "VISA.V 1 0222",
  • "dsTransID": "1f9b847b-8372-48fe-ade9-b628d3199d0e",
  • "transStatus": "C",
  • "resultsStatus": "01",
  • "transStatusReason": "01",
  • "outcome": {
    },
  • "resultCode": "TransactionAuthorised",
  • "messageVersion": "string"
}

Send Authentication

This endpoint will executed if the intiate endpoint returned method data. Method data will be sent to the ACS, the ACS once complete will post back to the Merchant URL. Once the Merchant receives the post the merchant will execute this endpoint to complete the 3DS transaction.

Request Body schema: application/json

This class contains the required information needed to perform the send auth request.

transactionUniqueIdentifier
string <uuid>

The transaction unique identifier for the 3DS transaction.

methodCompletionIndicator
string
Default: "Y"

Indicates whether the 3DS Method was successfully completed or not. Y=(default) Successfully completed, N=Did not successfully complete (Set this value if ACS has not responded in 10 seconds). 3DS Method URL was not present in the PRes message data for the card range associated with the Cardholder Account Number.

Responses

Request samples

Content type
application/json
{
  • "transactionUniqueIdentifier": "548dec7c-e572-47b9-ab77-028b9490a1d5",
  • "methodCompletionIndicator": "Y"
}

Response samples

Content type
application/json
Example
{
  • "authenticationECI": "05",
  • "authenticationValue": "AAABBZEEBgAAAAAAAAQGAAAAAAA=",
  • "transactionStatus": "Successful",
  • "transactionUniqueIdentifier": "1f9b847b-8372-48fe-ade9-b628d3199d0e",
  • "acsOperatorID": "ACS-V210-SOUTH-BAN-2121",
  • "acsTransID": "1f9b847b-8372-48fe-ade9-b628d3199d0e",
  • "acsReferenceNumber": "3DS_LOA_ACS_MOBL_1_1",
  • "authenticationType": "03",
  • "acsChallengeMandated": "Y",
  • "dsReferenceNumber": "VISA.V 1 0222",
  • "dsTransID": "1f9b847b-8372-48fe-ade9-b628d3199d0e",
  • "transStatus": "C",
  • "resultsStatus": "01",
  • "transStatusReason": "01",
  • "outcome": {
    },
  • "resultCode": "TransactionAuthorised",
  • "messageVersion": "2.1.0"
}

Get 3DS Transaction Information

This endpoint will return the 3DS Transaction Information.

query Parameters
transactionUniqueIdentifier
required
string <uuid>
Example: transactionUniqueIdentifier=f5819e1a-b759-494b-b1f4-c7b3bafafd7c

The unique identifier for the transaction.

Responses

Response samples

Content type
application/json
{
  • "authenticationECI": "05",
  • "authenticationValue": "AAABBZEEBgAAAAAAAAQGAAAAAAA=",
  • "transactionStatus": "Successful",
  • "messageVersion": "string",
  • "acsOperatorID": "ACS-V210-SOUTH-BAN-2121",
  • "acsTransID": "1f9b847b-8372-48fe-ade9-b628d3199d0e",
  • "acsReferenceNumber": "3DS_LOA_ACS_MOBL_1_1",
  • "authenticationType": "03",
  • "acsChallengeMandated": "Y",
  • "dsReferenceNumber": "VISA.V 1 0222",
  • "dsTransID": "1f9b847b-8372-48fe-ade9-b628d3199d0e",
  • "transStatus": "C",
  • "resultsStatus": "01",
  • "transStatusReason": "01",
  • "outcome": {
    }
}

Tokenization

Tokenization Services. This section contains the tokenization endpoints Tokenization, when applied to data security, is the process of substituting a sensitive data element with a non-sensitive equivalent, referred to as a token, that has no extrinsic or exploitable meaning or value.

Gets all the card details

Gets the card details of all the records by provided user id and shopper id

Authorizations:
TokenAuthorizer
query Parameters
merchantShopperReference
string <uuid>
Example: merchantShopperReference=f5819e1a-b759-494b-b1f4-c7b3bafafd7c

A unique identifier for a specific merchant customer.

header Parameters
authorization
required
string

Bearer token used to authenticate the request.

Responses

Response samples

Content type
application/json
{
  • "tokens": [
    ],
  • "outcome": {
    }
}

Remove all the card details

Remove all the saved records that relate to both provided user id and shopper id

Authorizations:
TokenAuthorizer
query Parameters
merchantShopperReference
required
string <uuid>
Example: merchantShopperReference=f5819e1a-b759-494b-b1f4-c7b3bafafd7c

A unique identifier for a specific merchant customer.

header Parameters
authorization
required
string

Bearer token used to authenticate the request.

Responses

Response samples

Content type
application/json
{
  • "status": "FAILURE",
  • "responseCode": "U01",
  • "reasonDescription": "Internal Server Error."
}

Remove a token

Removes the record based on the provided token, user id, shopper id and token type

Authorizations:
TokenAuthorizer
path Parameters
token
required
string <uuid>
Example: 31434579-84a2-43d4-aa59-236f86aabebf

Encrypted string, associated with card details

query Parameters
merchantShopperReference
string <uuid>
Example: merchantShopperReference=f5819e1a-b759-494b-b1f4-c7b3bafafd7c

A unique identifier for a specific merchant customer.

tokenType
required
string (tokenTypeEnum)
Enum: "Recurring" "OneClickPayment"
Example: tokenType=Recurring

The type of the payment that uses tokenization

header Parameters
authorization
required
string

Bearer token used to authenticate the request.

Responses

Response samples

Content type
application/json
{
  • "status": "FAILURE",
  • "responseCode": "U01",
  • "reasonDescription": "Internal Server Error."
}

Update a token

All the card details could be updated for a specific token except for the card number

Authorizations:
TokenAuthorizer
path Parameters
token
required
string <uuid>
Example: 31434579-84a2-43d4-aa59-236f86aabebf
header Parameters
authorization
required
string

Bearer token used to authenticate the request.

Request Body schema: application/json

Request body for endpoint updating the stored card details

>= 3 properties
merchantShopperReference
string <uuid>

The ID of the specific shopper

tokenType
required
string (tokenTypeEnum)
Enum: "Recurring" "OneClickPayment"

The type of the payment that uses tokenization

cardholderName
string

The name of the owner of the card

expiryYear
string

The year of expiration of the card.

expiryMonth
string

The month of expiration of the card.

Responses

Request samples

Content type
application/json
{
  • "merchantShopperReference": "f5819e1a-b759-494b-b1f4-c7b3bafafd7c",
  • "tokenType": "Recurring",
  • "cardholderName": "Mr Joe Doe",
  • "expiryYear": "25",
  • "expiryMonth": "12"
}

Response samples

Content type
application/json
{
  • "status": "FAILURE",
  • "responseCode": "U01",
  • "reasonDescription": "Internal Server Error."
}

Register a token

Encypts all the card details with the security service, stores them returns the created token

header Parameters
authorization
required
string

Bearer token used to authenticate the request.

Request Body schema: application/json

Request body for endpoint taking card details, stores them and returns created token

merchantShopperReference
string <uuid>

A unique identifier that can be provided to link a token key to a specific merchant customer.

tokenType
required
string (tokenTypeEnum)
Enum: "Recurring" "OneClickPayment"

The type of the payment that uses tokenization

required
object (registerTokenizedCardInformation)

Responses

Request samples

Content type
application/json
{
  • "merchantShopperReference": "f5819e1a-b759-494b-b1f4-c7b3bafafd7c",
  • "tokenType": "Recurring",
  • "cardInformation": {
    }
}

Response samples

Content type
application/json
{
  • "token": "31434579-84a2-43d4-aa59-236f86aabebf",
  • "tokenType": "Recurring",
  • "merchantShopperReference": "jane_at_global_shop",
  • "cardInformation": {
    },
  • "outcome": {
    }
}

ApplePay

ApplePay Services This section contains the endpoints required by merchants to enable them to accept ApplePay payments.

Create Merchant session

Creates an ApplePay Merchant Session to use for payment processing.

Request Body schema: application/json
mid
required
string

The unique identifier issued to the merchant by Truevo.

tid
required
string

The identity of the terminal utilised in the transaction.

domain
required
string

The registered domain of the merchant.

Responses

Request samples

Content type
application/json
{
  • "mid": "string",
  • "tid": "string",
  • "domain": "dwx764y2c7oz.cloudfront.net"
}

Response samples

Content type
application/json
{
  • "appleSession": "{\\\"epochTimestamp\\\":1649177537797,\\\"expiresAt\\\":1649181137797,\\\"merchantSessionIdentifier\\\":\\\"SSHF71D00F17933461DAC45B068B65DE1BD_916523AAED1343F5BC5815E12BEE9250AFFDC1A17C46B0DE5A943F0F94927C24\\\",\\\"nonce\\\":\\\"14a4fe69\\\",\\\"merchantIdentifier\\\":\\\"1D867D2918895F195CF99A0BCCA8B3E63C0AB3FC997F254501617482BBCF21F9\\\",\\\"domainName\\\":\\\"fd5eaedd-7d85-44c0-a49c-b3946d13c728\\\",\\\"displayName\\\":\\\"Mimi\\\",\\\"signature\\\":\\\"308006092a864886f70d010702a0803080020101310f300d06096086480165030402010500308006092a864886f70d0107010000a080308203e43082038ba003020102020859d8a1bcaaf4e3cd300a06082a8648ce3d040302307a312e302c06035504030c254170706c65204170706c69636174696f6e20496e746567726174696f6e204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b3009060355040613025553301e170d3231303432303139333730305a170d3236303431393139333635395a30623128302606035504030c1f6563632d736d702d62726f6b65722d7369676e5f5543342d53414e44424f5831143012060355040b0c0b694f532053797374656d7331133011060355040a0c0a4170706c6520496e632e310b30090603550406130255533059301306072a8648ce3d020106082a8648ce3d030107034200048230fdabc39cf75e202c50d99b4512e637e2a901dd6cb3e0b1cd4b526798f8cf4ebde81a25a8c21e4c33ddce8e2a96c2f6afa1930345c4e87a4426ce951b1295a38202113082020d300c0603551d130101ff04023000301f0603551d2304183016801423f249c44f93e4ef27e6c4f6286c3fa2bbfd2e4b304506082b0601050507010104393037303506082b060105050730018629687474703a2f2f6f6373702e6170706c652e636f6d2f6f63737030342d6170706c65616963613330323082011d0603551d2004820114308201103082010c06092a864886f7636405013081fe3081c306082b060105050702023081b60c81b352656c69616e6365206f6e207468697320636572746966696361746520627920616e7920706172747920617373756d657320616363657074616e6365206f6620746865207468656e206170706c696361626c65207374616e64617264207465726d7320616e6420636f6e646974696f6e73206f66207573652c20636572746966696361746520706f6c69637920616e642063657274696669636174696f6e2070726163746963652073746174656d656e74732e303606082b06010505070201162a687474703a2f2f7777772e6170706c652e636f6d2f6365727469666963617465617574686f726974792f30340603551d1f042d302b3029a027a0258623687474703a2f2f63726c2e6170706c652e636f6d2f6170706c6561696361332e63726c301d0603551d0e041604140224300b9aeeed463197a4a65a299e4271821c45300e0603551d0f0101ff040403020780300f06092a864886f76364061d04020500300a06082a8648ce3d0403020347003044022074a1b324db4249430dd3274c5074c4808d9a1f480e3a85c5c1362566325fbca3022069369053abf50b5a52f9f6004dc58aad6c50a7d608683790e0a73ad01e4ad981308202ee30820275a0030201020208496d2fbf3a98da97300a06082a8648ce3d0403023067311b301906035504030c124170706c6520526f6f74204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b3009060355040613025553301e170d3134303530363233343633305a170d3239303530363233343633305a307a312e302c06035504030c254170706c65204170706c69636174696f6e20496e746567726174696f6e204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b30090603550406130255533059301306072a8648ce3d020106082a8648ce3d03010703420004f017118419d76485d51a5e25810776e880a2efde7bae4de08dfc4b93e13356d5665b35ae22d097760d224e7bba08fd7617ce88cb76bb6670bec8e82984ff5445a381f73081f4304606082b06010505070101043a3038303606082b06010505073001862a687474703a2f2f6f6373702e6170706c652e636f6d2f6f63737030342d6170706c65726f6f7463616733301d0603551d0e0416041423f249c44f93e4ef27e6c4f6286c3fa2bbfd2e4b300f0603551d130101ff040530030101ff301f0603551d23041830168014bbb0dea15833889aa48a99debebdebafdacb24ab30370603551d1f0430302e302ca02aa0288626687474703a2f2f63726c2e6170706c652e636f6d2f6170706c65726f6f74636167332e63726c300e0603551d0f0101ff0404030201063010060a2a864886f7636406020e04020500300a06082a8648ce3d040302036700306402303acf7283511699b186fb35c356ca62bff417edd90f754da28ebef19c815e42b789f898f79b599f98d5410d8f9de9c2fe0230322dd54421b0a305776c5df3383b9067fd177c2c216d964fc6726982126f54f87a7d1b99cb9b0989216106990f09921d00003182018c30820188020101308186307a312e302c06035504030c254170706c65204170706c69636174696f6e20496e746567726174696f6e204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b3009060355040613025553020859d8a1bcaaf4e3cd300d06096086480165030402010500a08195301806092a864886f70d010903310b06092a864886f70d010701301c06092a864886f70d010905310f170d3232303430353136353231375a302a06092a864886f70d010934311d301b300d06096086480165030402010500a10a06082a8648ce3d040302302f06092a864886f70d0109043122042015f4113d9bb9fb087f3fdc867337588922f74a1aaa18bb660471de5e8d89db3f300a06082a8648ce3d04030204473045022100ac4b9c03be7813a6c26c8d2953261b7d5119f7d27ff0b6feaf062df838e147dc022061e1d7cb5331b466649ba6559ee75eb3b891b61e31c51076433886240bef13c2000000000000\\\",\\\"operationalAnalyticsIdentifier\\\":\\\"Mimi:1D867D2918895F195CF99A0BCCA8B3E63C0AB3FC997F254501617482BBCF21F9\\\",\\\"retries\\\":0,\\\"pspId\\\":\\\"1D867D2918895F195CF99A0BCCA8B3E63C0AB3FC997F254501617482BBCF21F9\\\"}",
  • "outcome": {
    }
}

AutoReversals

Initiates automated reversals on behalf of merchants in the event of communication failures, system issues or client-side clean up functions.

Reverse by Merchant Reference

This endpoint will initiate a reversal process using the Merchant Reference to identify the transaction to reverse.

path Parameters
merchantReference
required
string
Example: 123

The unique reference value allocated by the merchant to identify a transaction.

Request Body schema: application/json
mid
required
string

The unique identifier issued to the merchant.

tid
required
string

The identity of the terminal utilised in the transaction.

Responses

Request samples

Content type
application/json
{
  • "mid": "string",
  • "tid": "string"
}

Response samples

Content type
application/json
{
  • "transactionUniqueIdentifier": "5333e985-4779-456c-8ac3-a69d89c920e1",
  • "merchantReference": "8884-001",
  • "outcome": {
    }
}

Transaction Data

Payment Details

Retrieve details required to process transactions subsequent to successful processing of the original transaction.

query Parameters
transactionUniqueIdentifier
required
string
Example: transactionUniqueIdentifier=693559D9-3976-4B66-994E-DBDB7C1E6C4A

The unique identifier of the transaction for which you want to view the details.

header Parameters
authorization
required
string
Example: bearer token

Bearer token used to authenticate the request.

Responses

Response samples

Content type
application/json
{
  • "paymentDetails": {
    },
  • "outcome": {
    }
}

BIN Lookup

Retrieve the Bin lookup Result

Retrieve a single metadata record for the card specified by the Primary Account Number (PAN), Bank Identification Number (BIN) or token

Request Body schema: application/json
One of
object

Request for the relevant card information

simple (integer) or card_payouts (integer) or full (integer) (binLookupRequestFormat)

Responses

Request samples

Content type
application/json
Example
[
  • {
    }
]

Response samples

Content type
application/json
Example
{
  • "rangeDetails": [
    ]
}