Complete Payment Request

Method: HTTP POST

Format: JSON

Direction: POS (integrator) -> Gateway

After a payment has been authorised via the Payment request, the POS must issue a Complete Payment request to the gateway indicating whether it is accepting or rejecting the payment. The gateway will not settle an authorised transaction to the merchant's acquirer until the POS has issued a Complete Payment request. If the POS issues a Complete Payment request indicating rejection of the transaction, the gateway will process a reversal of the transaction to the acquirer.

The POS must send through the TransactionRRN (a unique transaction reference as returned in the Payment response) in any Complete Payment request whether the transaction is accepted or rejected.

Request

The Complete Payment request is constructed with the following sections:

CompletePaymentRequest
{
          Header{…}
          Detail{…}
          TargetTerminal{…}
}

Header Section

Field

Min

Max

Format

Description

ProtocolVersion

3

3

"^([0-9.]*)$"

Packet protocol version. Set as 1.0.

MerchantId

5

12

"^([a-zA-Z0-9-_]*)$"

Each merchant (site) is assigned a unique merchant identifier that must be presented in each request.

PosID

1

32

"^([a-zA-Z0-9-_]*)$"

POS should indicate the name of the POS station. This value is not used by the gateway but will be echoed back in the Payment response.

ClientDateTime

25

25

"YYYY-MM-DDTHH:mm:ss+hh:mm"

Date and time of the POS with time zone offset from GMT.

ClientTransactionReference

36

36

"^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89aAbB][a-f0-9]{3}-[a-f0-9]{12}$"

POS must create a GUID for the transaction and present it in the request in this field.

Attempt

1

5

"^([0-9]*)$"

This field should always be set to '1'. If the POS does not receive a response to a Complete Payment request, it can reissue another Complete Payment request but with a newly created ClientTransactionReference.

 

Detail Section

Field

Min

Max

Format

Description

TransactionRRN

1

32

"^([0-9]*)$"

This is the unique transaction ID returned in the Payment response.

ConfirmType

1

1

"^[A]|[C]|[D]$"

This field specifies if the POS wants to accept, reject, or decline the payment. Valid values are the following:

A: Accept the payment (settle the transaction)

C: Cancel (reverse) the payment

D: Decline the payment

Note: Decline payment is only appropriate in referral situations where the voice authorisation centre has verbally declined the payment. Referrals are currently not supported.

VoiceAuthCode

0

8

"^([a-zA-Z0-9])*$"

If the payment was referred and a voice authorisation verbally authorises the payment, this field must contain the verbal authorisation code.

Note: Referrals are currently not supported.

OriginalTransactionAmount

1

10

"^([0-9]*)$"

This field must contain the original TransactionAmount submitted in the Payment request.

OriginalTransactionDateTime

25

25

"YYYY-MM-DDTHH:mm:ss+hh:mm"

This field must contain the original TransactionDateTime submitted in the Payment request.

 

TargetTerminal Section

Field

Min

Max

Format

Description

TerminalName

8

8

"^([0-9]*)$"

Terminal identifier of the card terminal on which the payment was originally performed.

 

Response

The Complete Payment response is constructed with the following sections:

CompletePaymentResponse
{
          Header{…}
          Detail{…}
          ReceiptData{…}
}

Header Section

Field

Min

Max

Format

Description

ProtocolVersion

3

3

"^([0-9.]*)$"

Packet protocol version. Set as 1.0.

MerchantId

5

12

"^([a-zA-Z0-9-_]*)$"

Each merchant (site) is assigned a unique merchant identifier that must be presented in each request.

PosID

1

32

"^([a-zA-Z0-9-_]*)$"

POS ID echoed back from the Complete Payment request.

ClientTransactionReference

36

36

"^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89aAbB][a-f0-9]{3}-[a-f0-9]{12}$"

ClientTransactionReference echoed back from the Complete Payment request.

 

Detail Section

Field

Min

Max

Format

Description

ResponseCode

1

1

"^[A]|[C] $"

This field indicates the outcome of the Complete Payment request. Valid values are the following:

A: Payment has been accepted (and will settle).

C: Payment has been cancelled.

ResponseMessage

1

32

"^([a-zA-Z0-9-_: ])*$"

Verbose message such as 'AUTH CODE: xyz' for an authorised transaction or 'CANCELLED' for a cancelled transaction. 

 

ReceiptData Section

Field

Min

Max

Format

Description

CustomerReceipt

1

4096

"^([a-zA-Z0-9-_:# ])*$"

This field contains a constructed customer receipt with each line of the receipt separated by a '#' character. For receipt printing purposes, the POS should replace the '#' character with a linefeed / carriage return and send to the printer.

Receipts data are returned without a site name and address. The POS needs to prepend this information to the receipt data before printing.

MerchantReceipt

1

4096

"^([a-zA-Z0-9-_:# ])*$"

This field contains a constructed merchant receipt with each line of the receipt separated by a '#' character. For receipt printing purposes, the POS should replace the '#' character with a linefeed / carriage return and send to the printer.

Receipts data are returned without a site name and address. The POS needs to prepend this information to the receipt data before printing.

 

Complete Payment Request Example

{
            "CompletePaymentRequest":
            {
                        "Header":
                        {
                                    "ProtocolVersion":1.0, 
                                    "MerchantId":"PRCLIENT-CLOUDRETAIL-IRL",
                                    "PosID":"90005504",
                                    "ClientDateTime":"2023-02-09T08:48:11+00:00",
                                    "ClientTransactionReference":"559b629a-c4b9-41dc-a890-961e2ae0d3a1",
                                    "Attempt":1

                        },
                        "Detail":
                        {
                                    "TransactionRRN":"107002427378",
                                    "ConfirmType":"A",
                                    "VoiceAuthCode":"",
                                    "OriginalTransactionAmount":1000,
                                    "OriginalTransactionDateTime":"2023-02-09T08:47:31+00:00"
                        },
                        "TargetTerminal":
                        {
                                    "TerminalName":"90005504"
                        }
            }
}

Complete Payment Response Example

{
            "CompletePaymentResponse":
            {   
                        "Header":
                        {      
                                    "ProtocolVersion": 1.0,
                                    "MerchantId": "PRCLIENT-CLOUDRETAIL-IRL",
                                    "PosID": "90005504",
                                    "ClientTransactionReference": "559b629a-c4b9-41dc-a890-961e2ae0d3a1",
                                    "Attempt": 1
                        },
                        "Detail":
                        {
                                    "ResponseCode": "A",
                                    "ResponseMessage": "AUTH CODE: 185"
                        },
                        "ReceiptData":
                        {       
                                    "CustomerReceipt": "MID: 7888585866             TID:90005504##     KEEP THIS COPY FOR YOUR RECORDS...",
                                    "MerchantReceipt": "MID: 7888585866             TID:90005504##     KEEP THIS COPY FOR YOUR RECORDS..."
                        }
            }
}