API flows

Authentication

To authenticate, include the mandatory authentication object, containing the userId, password, and entityId fields, in the request body. The authentication object is used to verify that the request originated from a valid merchant using a valid payment method for a specific currency.

Payment flow

  1. The merchant initiates the call to create a new transaction by making a request to the Payments API endpoint.
  2. The Payments API returns a response with a 000.200.000 result code indicating that the transaction has been created, is in a pending state, and is now awaiting payment.
  3. The Payments API sends a webhook to the merchant with the same result code, informing them that the transaction has been updated from processing to pending. The merchant should expect webhooks whenever the transaction changes status.
  4. The merchant must redirect the user to the URL in the redirect object, including the parameters as query strings where relevant.
  5. The payment brand user interface displays to capture the user’s payment information.
  6. The user submits the required information.
  7. The Payments API redirects back to the URL specified in shopperResultUrl.
  8. The merchant executes the transaction status API request to retrieve the final transaction status.
  9. The Payments API sends a webhook to the merchant notifying them of the outcome of the transaction. For successful transactions, the webhook has the 000.000.000 result code.
Payment flow.Payment flow.

Payment flow.

Refund flow

The refund flow uses the same endpoint as the debit flow. However, the refund endpoint requires the original transaction ID as a path parameter, for example, /payments/{unique_transaction_id}/ and the payment type must be set to RF.

  1. The merchant makes a request to the refund endpoint with the transaction ID of the original transaction.

  2. For asynchronous refunds, the Payments API returns a pending result code (000.200.000) and the transaction transitions to a final state when the PSP has processed the refund.

    For synchronous refunds, the Payments API returns either a successful or failure result code. The merchant receives a webhook for each transaction status change. The merchant can use the transaction status API call to verify the status of a transaction at any time.

Refund flow.Refund flow.

Refund flow.

Transaction status flow

  1. The merchant sends a transaction status request to the Payments API.
  2. The Payments API responds, with the result code indicating the status of the transaction.
Transaction status flow.Transaction status flow.

Transaction status flow.

Webhook flow

Webhooks provide updates on any changes in the state of the transaction. They are sent regardless of whether the transaction succeeded or failed. The webhook request body is encrypted and you must decrypt it in order to process the transaction data.

  1. The merchant receives a webhook with a result code indicating the updated transaction status.
  2. The merchant returns a 200 status code response acknowledging the webhook.
Webhook flow.Webhook flow.

Webhook flow.

📘

To decrypt the webhook, please see these examples. Some of the decryption examples are specific to AES 256, these must be modified for AES 128 to match the relevant Peach Payments decryption key.

Postman workspace

See our Postman workspace for sample calls.