Menu

Alipay API information

IPS V3.1.2.0
Released August 2021

Shoppers can use Alipay to pay at point of sale or online.

API call

For the Alipay payments we have the API call:

v1/payment

This handles all the various payment instruments (card, Alipay). The difference between Alipay and a card payment is in the paymentInstrument section of the request. This shows the payment method used.

Example request for Alipay transaction:

Copied!
{
  "paymentType": "sale",
  "merchantTransactionReference": "MS123A54B3DF",
  "instruction": {
    "value": {
      "amount": 1099
    }​​​​​​​,
    "narrative": {
      "line1": "Transactiondescription"
    }​​​​​​​,
    "paymentInstrument": {
      "type": "alipay/barcode",
      "barcode": "1234567890123456"
    }
  }
}
Compare to a card payment:
{
  "paymentType": "sale",
  "merchantTransactionReference": "MS123A54B3DF",
  "instruction": {
    "value": {
      "amount": 1099
    }​​​​​​​,
    "paymentInstrument": {
      "type": "card/present"
    }
  }
}

Processing sequences

The diagrams below show the interaction between the EPOS, IPS, Integrated POS (Emboss) services. The interactions are for:

Sales- A sales transaction

Refund- A transaction where you refund the shopper their money

Cancelled- A transaction that is cancelled for some reason

Key for the diagrams below

Blue lines show the exchanging progress messages from IPS to the EPOS application.

Black lines show the data that is exchanged between applications.

Sales

The diagram below shows the interaction between the EPOS, IPS, Integrated POS (Emboss) service:

Sales transaction

The sequence in the diagram is below. The number of the step corresponds to the number of the arrow in the diagram:

  1. Sales transaction requestSee the code example below.

  2. Please wait Notification: Message send to EPOS "Please Wait."

  3. Prepare Authorisation Request: Prepare Authorisation Request.

  4. Send Authorisation Request: Send Authorisation Request.

  5. Authorising Notification: Message send to EPOS "Authorising..."

  6. Process Payment Request: Process payment request.

  7. Authorisation Response Received: Authorisation Response Received.

  8. Check Authorisation Response: Check Authorisation Response.

  9. Mark the Transaction Reversal: Mark the transaction for reversal.

  10. Send Same Authorisation (Reversal) Request: Send Same Authorisation (Reversal) Request to Integrated POS service (Emboss).

  11. Prepare Capture Request for Decline Transaction: Prepare Capture Request for Decline Transaction.

  12. Send Capture Request to the Integrated POS service (EMBOSS): Send Capture Request to the the Integrated POS service (EMBOSS).

  13. Prepare Query Request: Prepare Query Request.

  14. Send Query Request to EMBOSS: Send Query Request to the Integrated POS service (EMBOSS).

  15. Prepare Cancel Request: Send Capture Request to the Integrated POS service (EMBOSS).

  16. Send Cancel Request: Send Cancel Request.

  17. Prepare Capture Request for Decline Transaction: Prepare Capture Request for Decline Transaction.

  18. Send Capture Request to the Integrated POS service (EMBOSS): Send Capture Request to the Integrated POS service (EMBOSS).

  19. Approved Notification: Message sent to EPOS is "Approved."

  20. Finalising Notification: Message sent to EPOS "Finalising."

  21. Prepare Capture Request for Approved Transaction: Prepare the Capture Request for Approved Transaction.

  22. Send Capture Request to EMBOSS: Send Capture Request to the Integrated POS service (EMBOSS).

  23. Send Merchant and Customer Receipt: Send Merchant and Customer Receipts.

  24. Send Response data: Send response data.

  25. Transaction Complete Notification: Transaction completed.

Sale code example

The sale transaction request code is:

Copied!
{
"paymentType": "sale", "merchantTransactionReference": "alipaytest62", "instruction": {
"value": {
"amount": 1000
},
"narrative": {
"line1": "Transactiondescription"
},
"paymentInstrument": {
"type": "alipay/barcode",
"barcode": "99460490222836415430", "sendAttempt": 1,
"quantity":1
}
}
}

Refund

The diagram below shows the interaction between the EPOS, IPS, Integrated POS (Emboss) service:

Refund transaction

The sequence in the diagram is below. The number of the step corresponds to the number of the arrow in the diagram:

  1. Refund Transaction RequestSee the code example below.

  2. Please wait Notification: Message send to EPOS "Please Wait."

  3. Prepare Authorisation Request: Prepare Authorisation Request.

  4. Send Authorisation Request: Send Authorisation Request.

  5. Authorising Notification: Message send to EPOS "Authorising.."

  6. Process Payment Request: Process payment request.

  7. Authorisation Response Received: Authorisation Response Received.

  8. Check Authorisation Response: Check Authorisation Response.

  9. Increment Send Attempt by 1 for every Recursive Request: Increment Send Attempt by 1 for every recursive request.

  10. Send Same Authorisation Requeste: Send Same Authorisation Request to EMBOSS.

  11. Prepare Capture Request for Decline Transaction: Prepare Capture Request for Decline Transaction.

  12. Send Capture Request to EMBOSS: Send Capture Request to EMBOSS.

  13. Prepare Cancel Request: Prepare Cancel Request.

  14. Send Cancel Request: Send Cancel Request.

  15. Prepare Capture Request for Decline Transaction: Prepare Capture Request for Decline Transaction.

  16. Send Capture Request to EMBOSS: Send Capture Request to EMBOSS.

  17. Approved Notification: Message send to EPOS "Approved."

  18. Finalizing Notification: Message send to EPOS "Finalizing.."

  19. Prepare Capture Request for Approved Transaction: Prepare Capture Request for Approved Transaction.

  20. Send Capture Request to EMBOSS: Send Capture Request to EMBOSS.

  21. Send Merchant and Customer Receipt: Send Merchant and Customer Receipts.

  22. Send Response data: Send response data.

  23. Transaction Complete Notification: Transaction Completed.

Refund code example

The sale transaction request code is:

Copied!
{
"paymentType": "refund", "merchantTransactionReference": "MS123A54B3DF", "instruction": {
"value": {
"amount": 1000
},
"narrative": {
"line1": "Transactiondescription"
},
"originalGatewayTransactionReference": "1234567890AB", "paymentInstrument": {
"type": "alipay/barcode",
"barcode": "99460490222836415430", "sendAttempt": 1,
"quantity":1
}
} 
}

Cancel

The diagram below shows the interaction between the EPOS, IPS, Integrated POS (Emboss) service:

Cancel transaction

The sequence in the diagram is below. The number of the step corresponds to the number of the arrow in the diagram:

  1. Cancel Transaction requestSee the code example below.

  2. Please wait Notification: Message send to EPOS "Please Wait."

  3. Prepare Cancel Request: Prepare cancel request.

  4. Send Cancel Request: Cancel request send to EMBOSS.

  5. Please wait Notification: Message send to EPOS "Please Wait"

  6. Process Payment Request: Process payment request.

  7. Cancel Response Received from EMBOSS: Cancel response received from EMBOSS.

  8. Check Cancel Response: Check Cancel Response Received from EMBOSS.

  9. Send Same Cancel Request to EMBOSS: Send same cancel request to EMBOSS.

  10. Mark Cancel Transaction Decline: Mark Cancel Transaction Decline.

  11. Decline Notification: Message send to EPOS "Cancel Decline."

  12. Mark Cancel Transaction Decline: Mark Cancel Transaction Decline.

  13. Decline Notification: Message send to EPOS "Cancel Decline."

  14. Mark Cancel Transaction Approved: Mark Cancel Transaction Approved.

  15. Approved Notification: Message send to EPOS "Cancel Approved."

  16. Send Customer & Merchant Receipt data. Send customer & Merchant receipt data to EPOS.

  17. Send Response data: send response data.

  18. Transaction Complete Notification: Transaction Completed.

Cancel code example

The cancel transaction request code is:

Copied!
{
"merchantTransactionReference": "alipaytest62", "gatewayTransactionReference": "PGTR2174101078", "paymentInstrument": {
"type": "alipay/barcode",
"barcode": "284618761605761157",
"sendAttempt": 1,
"quantity":1
}
}