Authentication

To authenticate, include the mandatory authentication object, containing the userId, password, and entityId fields, in the request body. The authentication object verifies 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 it has created the transaction, placed it 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 moved 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.

Refund flow

The refund flow uses the same endpoint as the debit flow, but the refund endpoint requires the original transaction ID as a path parameter, for example, /payments/{unique_transaction_id}/ and you must set the payment type 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.

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.

Webhook flow

Webhooks provide updates on any changes in the state of the transaction. The Payments API sends them regardless of whether the transaction succeeded or failed. You must decrypt the encrypted webhook request body 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.

📘

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

Postman workspace

See the Peach Payments Postman workspace for sample calls.