Chat 2 Pay API

Update application's integration status

put

This API can be used to disable/enable integration with Chat 2 Pay programmatically.

Authorizations

c2p

AuthorizationstringRequired

Chat 2 Pay API Key Authorization

Body

application/json

applicationUuidstringRequired

Unique identifier generated for each custom application the customer links to the account

statusstring · enumRequired

Status

Example: ACTIVATED/DEACTIVATEDPossible values:

Responses

200

Success

*/*

updateTimestring · date-timeOptional

Last modified time

401

Invalid Chat 2 Pay API key

*/*

404

Chat 2 Pay configuration not found

*/*

put

/api/v2/integration

HTTPcURLJavaScriptPython

PUT /api/v2/integration HTTP/1.1
Host: chat2pay-service.clickatell.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 59

{
  "applicationUuid": "text",
  "status": "ACTIVATED/DEACTIVATED"
}

{
  "updateTime": "2026-05-07T20:24:50.945Z"
}

Reverse authorization and void a capture

post

This API can be used to reverse payment authorizations or void unsettled captures that were performed via Chat 2 Pay. Reversals cannot be performed on settled payments – a refund will need to be performed via the Payment Gateway back-office.

Authorizations

c2p

AuthorizationstringRequired

Chat 2 Pay API Key Authorization

Path parameters

paymentLinkRefstringRequired

The unique reference number for the payment link generated

Responses

200

Success

*/*

transactionTypestring · enumOptional

The type of transaction executed

Possible values:

totalAmountnumberOptional

The total amount of the transaction

paymentGatewayDecisionstringOptional

Decision received back from the Payment Gateway for the payment request

paymentGatewayReqReferenceNumberstringOptional

Payment Reference number received back from the Payment Gateway for the payment request

paymentGatewayResponseTimestampstring · date-timeOptional

Timestamp received back from the Payment Gateway for the payment request

paymentGatewayResponseCodeinteger · int32Optional

Response code received back from the Payment Gateway for the payment request

paymentGatewayErrorDecisionstringOptional

Error description received back from Payment Gateway if error occurred

paymentGatewayAuthReconciliationReferenceNumberstringOptional

Unique number generated by Payment Gateway to identify the transaction for the payment request

cardTypestringOptional

The type of card used for the transaction, as received back from the Payment Gateway for the payment request

maskedCardNumberstringOptional

The masked card number used for the transaction, as received back from the Payment Gateway for the payment request

cardExpiryDatestringOptional

The expiry date of the card used for the payment, as received back from the Payment Gateway for the payment request

paymentStatusstringOptional

New payment status if it was changed

paymentStatusIdstringOptional

The ID of the new payment status

400

Operation failed because of Chat 2 Pay validation rules

*/*

401

Invalid Chat 2 Pay API key

*/*

404

Configured extension or transaction not found

*/*

x-payment-gateway-error-code

Payment gateway error

*/*

post

/api/v2/payment/{paymentLinkRef}/reverse

HTTPcURLJavaScriptPython

POST /api/v2/payment/{paymentLinkRef}/reverse HTTP/1.1
Host: chat2pay-service.clickatell.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "transactionType": "VOID",
  "totalAmount": 1,
  "paymentGatewayDecision": "VOIDED",
  "paymentGatewayReqReferenceNumber": "6432992054556063104004",
  "paymentGatewayResponseTimestamp": "2022-01-27T16:00:05.000+00:00",
  "paymentGatewayResponseCode": 200,
  "paymentStatus": "VOIDED",
  "paymentStatusId": "7"
}

Request to capture the payment amount

post

This API can be used to capture payment authorizations that were performed via Chat 2 Pay. Only one successful payment capture can be performed against one payment authorization (multiple partial captures against one authorization are not supported currently).

Authorizations

c2p

AuthorizationstringRequired

Chat 2 Pay API Key Authorization

Path parameters

paymentLinkRefstringRequired

The unique reference number for the payment link generated

Query parameters

amountnumberOptional

The amount for capture. The total amount will be used if not specified.

Responses

200

Success

*/*

transactionTypestring · enumOptional

The type of transaction executed

Possible values:

totalAmountnumberOptional

The total amount of the transaction

paymentGatewayDecisionstringOptional

Decision received back from the Payment Gateway for the payment request

paymentGatewayReqReferenceNumberstringOptional

Payment Reference number received back from the Payment Gateway for the payment request

paymentGatewayResponseTimestampstring · date-timeOptional

Timestamp received back from the Payment Gateway for the payment request

paymentGatewayResponseCodeinteger · int32Optional

Response code received back from the Payment Gateway for the payment request

paymentGatewayErrorDecisionstringOptional

Error description received back from Payment Gateway if error occurred

paymentGatewayAuthReconciliationReferenceNumberstringOptional

Unique number generated by Payment Gateway to identify the transaction for the payment request

cardTypestringOptional

The type of card used for the transaction, as received back from the Payment Gateway for the payment request

maskedCardNumberstringOptional

The masked card number used for the transaction, as received back from the Payment Gateway for the payment request

cardExpiryDatestringOptional

The expiry date of the card used for the payment, as received back from the Payment Gateway for the payment request

paymentStatusstringOptional

New payment status if it was changed

paymentStatusIdstringOptional

The ID of the new payment status

400

Operation failed because of Chat 2 Pay validation rules

*/*

401

Invalid Chat 2 Pay API key

*/*

404

Chat 2 Pay configuration or transaction not found

*/*

x-payment-gateway-error-code

Payment gateway error

*/*

post

/api/v2/payment/{paymentLinkRef}/capture

HTTPcURLJavaScriptPython

POST /api/v2/payment/{paymentLinkRef}/capture HTTP/1.1
Host: chat2pay-service.clickatell.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "transactionType": "CAPTURE",
  "totalAmount": 1,
  "paymentGatewayDecision": "PENDING",
  "paymentGatewayReqReferenceNumber": "6432990331036057204005",
  "paymentGatewayResponseTimestamp": "2022-01-27T15:57:13.000+00:00",
  "paymentGatewayResponseCode": 200
}

Generate and send a payment link

post

Generate and send a Chat 2 Pay message containing the payment link to the end-user and create a transaction log entry for the Chat 2 Pay request.

Authorizations

c2p

AuthorizationstringRequired

Chat 2 Pay API Key Authorization

Body

application/json

channelstring · enumRequired

The channel used to send the payment link to the end-user. Values: sms, whatsapp, none (only used if you do not want to send the payment link through a channel configured on Chat 2 Pay)

Possible values:

fromstringOptional

The mobile number of the sender used when sending payment link

tostringRequired

The end-user’s mobile number that the payment link must be sent to.

orderNumberstring · max: 32Required

The order number associated with this payment

timestampstring · date-timeRequired

The date and time that the system sends the request (ISO 8601 format)

currencystringRequired

The currency that the end-user is using to transact (Three-character ISO Standard Currency Codes)

Pattern: [A-Za-z]{3}

taxAmountnumberOptional

Tax due on this purchase

subTotalAmountnumberOptional

Amount due before tax

totalAmountnumberRequired

Amount that the end-user needs to pay

paymentGatewaySettingsIdstringOptional

ID of payment gateway settings if multiple payment gateway settings were configured

additionalDataobjectOptional

Any additional data over and above what is already included that you want to store in the database along with that record and/or return in the response

returnPaymentLinkbooleanOptional

Returns the payment link in the response if set to ‘true’

applicationIdstringOptional

Unique reference number generated by Clickatell to identify the client’s application. This ID can be retrieved from the Clickatell customer portal.

paymentReviewAutoReversalbooleanOptional

Make automatically transaction reversal in case of REVIEW state

Default: false

transactionTypestring · enumOptional

Specifies the type of transaction that will be performed by the Payment Gateway. Allowed values are: Sale or Authorization. If a value is not supplied, the default transaction type that was set as part of the payment settings for the Chat 2 Pay configuration in the Clickatell Portal will be used.

Possible values:

reconciliationIdstring · max: 60Optional

Reference number that you use to reconcile your transaction reports with your processor reports. Also known as Transaction Reference Number or TRN.

merchantDescriptorstringOptional

Merchant's business name. This name is displayed on the cardholder’s statement. Check your payment gateway integration guides for restrictions on maximum data length and allowed characters.

Responses

201

Payment link created

*/*

400

Invalid Chat 2 Pay request, various validation rules broken

*/*

401

Invalid Chat 2 Pay API key

*/*

404

Chat 2 Pay configuration not found

*/*

x-oneapi-error-code

HTTP error code that is returned from the channel API in case of an error when sending a message (see list of OneAPI error codes)

*/*

post

/api/v2/chat-2-pay

HTTPcURLJavaScriptPython

POST /api/v2/chat-2-pay HTTP/1.1
Host: chat2pay-service.clickatell.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 132

{
  "channel": "sms",
  "to": "16102347315",
  "currency": "USD",
  "orderNumber": "001",
  "totalAmount": 1,
  "timestamp": "2021-04-27T17:35:58.000+0000"
}

Minimum required fieldsAll fields with example valuesUsing 'none' channelOrder line items (example 1)Order line items (example 2)

{
  "paymentLinkRef": "00e5dbdb-541e-4f9b-9e93-5dccef6a0854",
  "transactionStatus": "PAYMENT_LINK_SENT",
  "transactionStatusId": 2,
  "timestamp": "2021-06-22T12:31:08.102+00:00"
}

Create payment receipt

post

Use this endpoint in conjunction with the Chat 2 Pay API to send your end-users a link to their order receipt via the same channel used to send the payment link.

Authorizations

c2p

AuthorizationstringRequired

Chat 2 Pay API Key Authorization

Body

application/json

receiptLinkstringRequired

The link that is sent to the end-user to direct them to their order receipt

paymentLinkRefstringRequired

The unique reference number for the payment link generated

timestampstring · date-timeRequired

The date and time the instruction to create the link was sent

Responses

201

Created, receipt link sent successfully

*/*

400

Created, receipt link sent failed

*/*

401

Invalid Chat 2 Pay API key

*/*

404

Chat 2 Pay configuration or transaction not found

*/*

x-oneapi-error-code

HTTP error code that is returned from the channel API in case of an error when sending a message (see list of OneAPI error codes)

*/*

post

/api/v2/order-receipt

HTTPcURLJavaScriptPython

POST /api/v2/order-receipt HTTP/1.1
Host: chat2pay-service.clickatell.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 144

{
  "paymentLinkRef": "6753076e-1ee0-4323-b13c-9f67799036c6",
  "timestamp": "2021-04-27T17:35:58.000+0000",
  "receiptLink": "https://your.domain/receipt"
}

{
  "receiptLinkRef": "0e5f63d3-8964-49cf-a3a0-3d6620a4f479",
  "orderNumber": "001",
  "timestamp": "2021-06-22T13:56:28.000+00:00",
  "transactionStatus": "RECEIPT_LINK_SENT",
  "transactionStatusId": 7
}

Cancels a payment link

post

This API can be used to cancel the payment link. It is only possible to cancel a payment link that hasn’t been clicked yet. The cancellation of a payment link doesn’t affect a payment that is in progress.

Authorizations

c2p

AuthorizationstringRequired

Chat 2 Pay API Key Authorization

Path parameters

paymentLinkRefstringRequired

The unique reference number for the payment link generated

Responses

200

Success

*/*

paymentLinkRefstringOptional

Payment Link Reference Number

transactionStatusstringOptional

Transaction status of payment link

transactionStatusIdstringOptional

The ID of transaction status for payment link

additionalDatastringOptional

Additional data field for payment link

timestampstring · date-timeOptional

Timestamp of payment link

400

Operation failed because of validation rules

*/*

401

Invalid Chat 2 Pay API key

*/*

404

Configured extension or transaction not found

*/*

post

/api/v2/cancel/{paymentLinkRef}

HTTPcURLJavaScriptPython

POST /api/v2/cancel/{paymentLinkRef} HTTP/1.1
Host: chat2pay-service.clickatell.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "paymentLinkRef": "621ff1eb-8eee-4f0e-a2d0-490bb82003d2",
  "transactionStatus": "Payment Link Cancelled",
  "transactionStatusId": "19",
  "additionalData": "null",
  "timestamp": "2022-02-14T11:38:04.249+00:00"
}

Get transaction details

get

Get a detailed breakdown of a transaction, including the transaction statuses and payment outcome.

Authorizations

c2p

AuthorizationstringRequired

Chat 2 Pay API Key Authorization

Query parameters

orderNumberstringOptional

The order number associated with the payment

paymentLinkRefstringOptional

The payment link reference of the transaction you requested the details for

receiptLinkRefstringOptional

The unique reference number for the receipt link generated

Responses

200

Success

*/*

orderNumberstringOptional

The order number associated with the payment

paymentLinkRefstringOptional

The payment link reference of the transaction you requested the details for

paymentStatusstring · enumOptional

The status of the payment

Possible values:

paymentStatusIdstringOptional

The ID of the payment status

paymentStatusTimestampstring · date-timeOptional

The date and time the payment outcome from the Payment Gateway was received (ISO 8601 format)

totalAmountnumberOptional

The total amount of the transaction

receiptLinkRefstringOptional

The receipt link reference number for the transaction

channelNamestringOptional

The name of the channel used for the transaction

currencystringOptional

The currency that the transaction was conducted in

taxAmountnumberOptional

The tax amount of the transaction

subTotalAmountnumberOptional

The sub-total of the transaction (before tax)

additionalDatastringOptional

Any additional data over and above what is already included that you want to store in the database along with that record and/or return in the response

paymentStatusConversionTimestring · date-timeOptional

This field will contain the timestamp received from the payment gateway when a transaction which was in a Review status was finalized.

paymentReviewAutoReversalbooleanOptional

Make automatically transaction reversal in case of REVIEW state

Default: false

transactionTypestring · enumOptional

Specifies the type of transaction that was be performed by Payment Gateway.

Possible values:

environmentstringOptional

Chat 2 Pay configuration run environment (SANDBOX or PRODUCTION)

reconciliationIdstringOptional

Reference number that you use to reconcile your transaction reports with your processor reports. Also known as Transaction Reference Number or TRN.

merchantDescriptorstringOptional

Merchant's business name.

401

Invalid Chat 2 Pay API key

*/*

get

/api/v2/chat-2-pay/transaction-status

HTTPcURLJavaScriptPython

GET /api/v2/chat-2-pay/transaction-status HTTP/1.1
Host: chat2pay-service.clickatell.com/
Authorization: YOUR_API_KEY
Accept: */*

[
  {
    "orderNumber": "v2-01",
    "paymentLinkRef": "16a14fe3-d145-4e70-8fc2-fe6b5155e9cf",
    "transactionStatuses": [
      {
        "transactionStatusId": 12,
        "transactionStatusName": "Payment Status Notification Delivery Successful",
        "created": "2022-02-10T10:13:41.000+00:00"
      },
      {
        "transactionStatusId": 5,
        "transactionStatusName": "Payment Status Notification Sent",
        "created": "2022-02-10T10:13:15.000+00:00"
      },
      {
        "transactionStatusId": 4,
        "transactionStatusName": "Payment Status Received",
        "created": "2022-02-10T10:12:52.000+00:00"
      },
      {
        "transactionStatusId": 20,
        "transactionStatusName": "Payment Link Clicked",
        "created": "2022-02-10T10:10:40.000+00:00"
      },
      {
        "transactionStatusId": 1,
        "transactionStatusName": "Payment Link Request Received",
        "created": "2022-02-10T10:10:19.000+00:00"
      }
    ],
    "paymentStatuses": [
      {
        "transactionType": "AUTHORIZATION",
        "totalAmount": 10,
        "paymentGatewayDecision": "ACCEPT",
        "paymentGatewayReqReferenceNumber": "6444879418826376804001",
        "paymentGatewayResponseTimestamp": "2022-02-10T10:12:22.000+00:00",
        "paymentGatewayResponseCode": 100,
        "paymentGatewayAuthReconciliationReferenceNumber": "235314875619",
        "cardType": "Visa",
        "maskedCardNumber": "XXXXXXXXXXXX1111",
        "cardExpiryDate": "02/2022"
      }
    ],
    "paymentStatus": "SUCCESS",
    "paymentStatusId": "1",
    "paymentStatusTimestamp": "2022-02-10T10:13:40.000+00:00",
    "totalAmount": 10,
    "channelName": "NONE",
    "currency": "ZAR",
    "additionalData": "null",
    "integrator": {
      "applicationId": "95cbfe96-b53b-4fd0-b168-ea01072beb16",
      "name": "Custom App"
    },
    "paymentReviewAutoReversal": false,
    "transactionType": "AUTHORIZATION",
    "environment": "SANDBOX",
    "reconciliationId": "56343512"
  }
]

Get Chat 2 Pay configuration

get

This API returns the configuration data for the configured Chat 2 Pay product.

Authorizations

c2p

AuthorizationstringRequired

Chat 2 Pay API Key Authorization

Responses

200

Success

*/*

updateTimestring · date-timeOptional

Last modified time

whatsappChannelEnabledbooleanOptional

Checks if WA omni integration is enabled

smsChannelEnabledbooleanOptional

Checks if SMS omni integration is enabled

apiKeystringOptional

Api key

environmentstringOptional

Chat 2 Pay configuration run environment (SANDBOX or PRODUCTION)

401

Invalid Chat 2 Pay API key

*/*

get

/api/v2/config

HTTPcURLJavaScriptPython

GET /api/v2/config HTTP/1.1
Host: chat2pay-service.clickatell.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "updateTime": "2022-02-11T12:05:51.000+00:00",
  "whatsappChannelEnabled": false,
  "smsChannelEnabled": true,
  "integrators": [
    {
      "applicationId": "95cbfe96-b53b-4fd0-b168-ea01072beb16",
      "name": "Custom App",
      "status": "ACTIVATED"
    },
    {
      "applicationId": "1",
      "name": "Salesforce",
      "status": "ACTIVATED"
    },
    {
      "applicationId": "2",
      "name": "ChatDesk",
      "status": "ACTIVATED"
    }
  ],
  "apiKey": "0ba7430e091841b9a87e25f1946c3320",
  "supportedCurrencies": [
    {
      "id": 156,
      "iso": "ZAR",
      "name": "South African rand",
      "symbol": "R",
      "isDefault": true
    }
  ],
  "environment": "SANDBOX"
}