### Example Redirect Requests Source: https://developer.peachpayments.com/docs/payments-api-flows Provides examples of how to handle redirect requests for different payment methods, including GET and POST examples with form-urlencoded data. ```APIDOC ## Example Redirect Requests ### Description Provides examples of how to handle redirect requests for different payment methods, including GET and POST examples with form-urlencoded data. ### Example GET Redirect (ZeroPay) ```curl curl --location 'https://payment.ftapp.co.za/93db1f009fb944b2ab23efde702eaec1?reference=93db1f009fb944b2ab23efde702eaecz' ``` ### Example POST Redirect (Scan to Pay) ```curl curl --location 'https://testapi-v2.peachpayments.com/verify/' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'amount=10.00' \ --data-urlencode 'connector=MASTERPASS' \ --data-urlencode 'currency=ZAR' \ --data-urlencode 'transaction=867acdb32cd1451eb5a4b9bb3ac1994z' ``` ``` -------------------------------- ### Example GET Redirect Request for ZeroPay Source: https://developer.peachpayments.com/docs/payments-api-flows This example demonstrates how to make a GET request for ZeroPay redirects. It includes the base URL and a transaction reference parameter. ```curl curl --location 'https://payment.ftapp.co.za/93db1f009fb944b2ab23efde702eaec1?reference=93db1f009fb944b2ab23efde702eaecz' ``` -------------------------------- ### Example Requests and Responses Source: https://developer.peachpayments.com/docs/payments-api-flows Links to resources for sample API requests and responses. ```APIDOC ## Example Requests and Responses ### Description Access sample requests and responses for Peach Payments API interactions. ### Resources - **Interactive API Playground:** [https://developer.peachpayments.com/reference/payment](https://developer.peachpayments.com/reference/payment) - **Peach Payments Postman Collection:** [![Run in Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.io/run-collection/13324425-d68d2419-06ff-4a06-a6c5-2898fd0d89d1?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D13324425-d68d2419-06ff-4a06-a6c5-2898fd0d89d1%26entityType%3Dcollection%26workspaceId%3D395353be-fe74-499e-9ef1-fc3433748710#?env%5BPayments-Public%5D=W3sia2V5IjoiYmFzZVVybCIsInZhbHVlIjoiaHR0cHM6Ly90ZXN0YXBpLXYyLnBlYWNocGF5bWVudHMuY29tIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJhcGlVc2VybmFtZSIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZSwidHlwZSI6InNlY3JldCJ9LHsia2V5IjoiYXBpUGFzc3dvcmQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWUsInR5cGUiOiJzZWNyZXQifSx7ImtleSI6ImVudGl0eUlkIiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6InNob3BwZXJSZXN1bHRVcmwiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9XQ==) ``` -------------------------------- ### CSV Example for Bulk Payment Links Source: https://developer.peachpayments.com/docs/generate-bulk-payment-links This is an example CSV file format used for generating bulk payment links. It specifies required and optional fields such as invoice ID, amount, currency, customer details, and communication preferences. ```text INVOICE_ID,AMOUNT,CURRENCY,CUSTOMER_GIVEN_NAME,CUSTOMER_SURNAME,SEND_EMAIL,CUSTOMER_EMAIL INV-00002,10.00,ZAR,Grace,Nkosi,true,test@example.com INV-00003,15.00,ZAR,Rex,Bartoletti,true,test@example.com INV-00004,20.00,ZAR,Cali,Huel,true,test@example.com ``` -------------------------------- ### POST /checkout Source: https://developer.peachpayments.com/docs/checkout-payment-flow Initializes Hosted Checkout and prepares for a form POST redirect to the payment page. This method requires the signature to be generated on the backend and the POST request to be executed from the browser. ```APIDOC ## POST /checkout ### Description This endpoint initiates the Hosted Checkout process and is designed to be used with a form POST method. The client-side will execute a POST request to the Peach Payments gateway after the signature has been generated on the server. ### Method POST ### Endpoint https://testsecure.peachpayments.com/checkout ### Parameters #### Request Body - **amount** (string) - Required - The transaction amount. - **authentication.entityId** (string) - Required - The entity ID for authentication. - **currency** (string) - Required - The currency code for the transaction (e.g., ZAR). - **merchantTransactionId** (string) - Required - A unique identifier for the transaction generated by the merchant. - **nonce** (string) - Required - A unique, random string generated for each transaction to prevent replay attacks. - **paymentType** (string) - Required - The type of payment (e.g., 'DB' for debit). - **shopperResultUrl** (string) - Required - The URL to redirect the shopper to after the payment attempt. - **signature** (string) - Required - The HMAC SHA256 signature generated using the transaction parameters and the merchant's secret token. ### Request Example ```html
``` ### Response #### Success Response (302 Found) This endpoint typically returns a 302 Found status with a `Location` header pointing to the Peach Payments checkout page. The actual payment details are handled on the Peach Payments gateway. #### Response Example (Browser is redirected to the payment page. No direct JSON response is typically shown to the initiating server for this method.) ``` -------------------------------- ### GET /v2/channels/{entityId}/payment-methods Source: https://developer.peachpayments.com/docs/v2-checkout-payment-methods Queries the available payment methods for a specific entity ID and currency. The response includes a list of enabled payment methods and your merchant ID. ```APIDOC ## GET /v2/channels/{entityId}/payment-methods ### Description Retrieves a list of available payment methods for a given Peach Payments entity ID and currency. This is useful for ensuring that the payment methods offered to customers are up-to-date with the merchant's Peach Payments setup. ### Method GET ### Endpoint `/v2/channels/{entityId}/payment-methods` ### Parameters #### Path Parameters - **entityId** (string) - Required - The unique identifier provided by Peach Payments for your merchant account. #### Query Parameters - **currency** (string) - Required - The currency for which to retrieve payment methods (e.g., 'ZAR', 'USD'). ### Request Example ```bash GET https://testsecure.peachpayments.com/v2/channels/YOUR_ENTITY_ID/payment-methods?currency=ZAR ``` ### Response #### Success Response (200) - **merchantId** (string) - The merchant ID associated with the entity. - **paymentMethods** (array) - A list of available payment methods. Each payment method object may contain: - **method** (string) - The name of the payment method (e.g., 'creditcard', 'eft'). - **displayName** (string) - A user-friendly name for the payment method. - **active** (boolean) - Indicates if the payment method is currently active. #### Response Example ```json { "merchantId": "00000000-0000-0000-0000-000000000000", "paymentMethods": [ { "method": "creditcard", "displayName": "Credit Card", "active": true }, { "method": "eft", "displayName": "EFT", "active": true } ] } ``` ``` -------------------------------- ### Redirect-based Checkout Source: https://developer.peachpayments.com/docs/checkout-payment-flow Initiates the Hosted Checkout flow and returns a URL. The user is then redirected to this URL to complete the payment process on the Peach Payments hosted page. ```APIDOC ## POST /checkout-initiate ### Description This endpoint initiates a redirect-based Hosted Checkout flow. Upon a successful request, it returns a URL that the user should be redirected to in order to complete their payment. ### Method POST ### Endpoint [Refer to Peach Payments API documentation for the specific endpoint URL] ### Parameters #### Request Body - **amount** (string) - Required - The transaction amount. - **authentication.entityId** (string) - Required - The entity ID for authentication. - **currency** (string) - Required - The currency code for the transaction (e.g., ZAR). - **merchantTransactionId** (string) - Required - A unique identifier for the transaction generated by the merchant. - **nonce** (string) - Required - A unique, random string generated for each transaction to prevent replay attacks. - **paymentType** (string) - Required - The type of payment (e.g., 'DB' for debit). - **shopperResultUrl** (string) - Required - The URL to redirect the shopper to after the payment attempt. - **signature** (string) - Required - The HMAC SHA256 signature generated using the transaction parameters and the merchant's secret token. ### Request Example (Example omitted as the request structure is identical to the Form POST, differing mainly in the expected response and handling.) ### Response #### Success Response (200 OK) - **redirectUrl** (string) - The URL to which the user should be redirected to complete the payment. #### Response Example ```json { "redirectUrl": "https://testsecure.peachpayments.com/checkout/abcdef1234567890" } ``` ``` -------------------------------- ### Going Live with Peach Payments Source: https://developer.peachpayments.com/docs/reference-test-and-go-live Guidance on switching from sandbox to live credentials and API endpoints. ```APIDOC ## Going Live ### Description Once integration and testing are complete in the sandbox environment, switch to your live credentials to accept real payments. Ensure you update both your credentials and the API endpoints used in your code. ### Key Considerations * **Credentials**: Live API credentials differ from sandbox credentials. These **must** be swapped before going live. * **API Endpoints**: Live API endpoints differ from sandbox endpoints. Update your code to use the correct live endpoints for: * Embedded Checkout * Hosted Checkout * Shared Checkout functionality * Payment Links * Payments API * Payouts * Reconciliation API Refer to the API reference section for the 'Base URL' list, which contains both live and sandbox endpoints. ``` -------------------------------- ### MauCAS Simulator Testing Source: https://developer.peachpayments.com/docs/reference-test-and-go-live Instructions for enabling test mode for MauCAS against the simulator in the sandbox environment. ```APIDOC ## MauCAS Simulator Testing ### Description To test MauCAS against a simulator in the sandbox environment, include the following in your Payments API request body. This is not required when testing in Checkout. ### Method POST ### Endpoint /payments ### Parameters #### Request Body - **customParameters[enableTestMode]** (string) - Required - Set to `"true"` to enable test mode. ### Request Example ```json { "amount": 16.40, "customParameters": { "enableTestMode": "true" } } ``` ### Response #### Success Response (200) Details depend on the specific test scenario. #### Response Example ```json { "resultCode": "000.200.000", "amount": 16.40 } ``` ### Test Scenarios | Scenario | Amount | Result code | Notes | | :---------------------------- | :------ | :------------ | :------------------------------------------------------------------------------------ | | Pending transaction | `16.40` | `000.200.000` | Transaction status updated to successful after the expiry time (five minutes) elapses | | Error response from MauCAS | `15.40` | `600.100.100` | | | HTTP 5xx response from MauCAS | `16.30` | `900.100.100` | | | Transaction failure | `25.00` | `800.100.152` | Transaction status updated to failed in 30-90 seconds | | Transaction successful | `25.10` | `000.000.000` | Transaction status updated to successful in 30-90 seconds | ``` -------------------------------- ### GET /status Source: https://developer.peachpayments.com/docs/checkout-payment-flow Retrieves the status of a specific checkout transaction. This is useful after a customer has been redirected to your shopperResultUrl, or when processing webhook notifications. ```APIDOC ## GET /status ### Description Retrieves the status of a specific checkout transaction using the `checkoutId` as a reference. This endpoint is typically used after a customer is redirected to your `shopperResultUrl` or when processing webhook notifications. ### Method GET ### Endpoint `/status` ### Query Parameters - **authentication.entityId** (string) - Required - The unique identifier for your Peach Payments entity. - **merchantTransactionId** (string) - Required - The unique transaction ID generated by your merchant system. - **signature** (string) - Required - A signature generated to authenticate the request. ### Request Example ``` GET https://testsecure.peachpayments.com/status?authentication.entityId=8ac7a4c8708b8dae01708be6bb3b018e&merchantTransactionId=ffghfsdrererwsdsf&signature=99699bb4a04af65a762ec4d15363a3d79aa21a12786721e0e89fa6c98933fb18 ``` ### Response #### Success Response (200) - **checkoutId** (string) - The unique identifier for the checkout transaction. - **timestamp** (string) - The date and time of the status query. - **result** (object) - Contains details about the transaction result. - **code** (string) - The result code of the transaction. - **description** (string) - A description of the result code. - **status** (string) - The current status of the checkout transaction (e.g., "SUCCESS", "PENDING", "FAILED"). #### Response Example ```json { "checkoutId": "8a1a8908708f3b010000000000000000", "timestamp": "2023-10-27T10:00:00Z", "result": { "code": "000.100.100", "description": "Success" }, "status": "SUCCESS" } ``` ``` -------------------------------- ### Payflex Testing Source: https://developer.peachpayments.com/docs/reference-test-and-go-live Guidelines for testing Payflex in the sandbox environment. Requires pre-approval and provides specific test data for credentials, card details, and OTP. ```APIDOC ## Payflex Testing ### Description To test Payflex in the sandbox environment, you must first be added to their allowlist by contacting support. Use the provided test credentials and details. ### Test Details * **Email & Password:** Any email address and password * **ID number:** `9503095194084` * **Test card number:** `377091000152284` * **Test card CVV:** `7003` * **Test card expiry date:** `01/28` * **Phone number:** `0123456789` * **OTP:** `911911` * **Amount:** Anything from R10 to R50,000 ``` -------------------------------- ### Get Checkout Status V2 - cURL Request Source: https://developer.peachpayments.com/docs/v2-checkout-status This snippet shows how to make a GET request to the V2 Checkout Status endpoint using cURL. It requires the `checkoutId` in the URL and an 'Accept' header set to 'application/json'. This is a basic example for retrieving the current status of a specific checkout transaction. ```curl curl --location 'https://testsecure.peachpayments.com/v2/checkout/948cc8dec52a11eb85290242ac130003/status' \ --header 'Accept: application/json' ``` -------------------------------- ### Happy Pay Testing Source: https://developer.peachpayments.com/docs/reference-test-and-go-live Steps for testing Happy Pay in the sandbox environment. Requires creating a test account and simulates card payments. ```APIDOC ## Happy Pay Testing ### Description Test Happy Pay in the sandbox environment by first creating a test account on the Happy Pay registration page. You can only have one instalment payment active at a time, so create multiple accounts for multiple scenarios. ### Steps 1. Create a test account on [Happy Pay's QA registration page](http://qa.happypay.co.za/register_test). 2. In the sandbox environment, when the Happy Pay user interface appears, enter the email address of your created account and click **Login**. 3. Enter the password for the account and click **Login**. 4. Click **PAY IN INSTALMENTS**. 5. Accept the terms and conditions and click **Proceed**. 6. At the top of the Happy Pay user interface, click **Simulate Card**. ``` -------------------------------- ### Peach Payments Webhook Payload Example (Pending) Source: https://developer.peachpayments.com/docs/payments-api-flows This JSON snippet represents a webhook payload from Peach Payments for a 'Pending' transaction. It includes transaction details, customer information, and result codes indicating the payment process has started. ```json { "id":"02f2ef804c4f4713ab053661cba98d4z", "referencedId":"", "paymentType":"DB", "paymentBrand":"PEACHEFT", "amount":"1.0", "merchantTransactionId":"EFTTestdb7532d8d", "merchantInvoiceId":null, "merchantAccountId":"28f0a55c50e911eb88ef02de7a5a0a6z", "descriptor":"", "currency":"ZAR", "presentationAmount":"1.0", "presentationCurrency":"ZAR", "result":{ "code":"000.200.000", "description":"transaction pending" }, "resultDetails":{ "clearingInstituteName":"EFT", "ExtendedDescription":"Payment process started.", "AcquirerResponse":"PENDING" }, "connectorTxID1":null, "authentication":{ "entityId":"8ac7a4ca77a64c9c0177af52972c13bz" }, "card":{ "bin":null, "last4Digits":null, "holder":null, "type":null, "expiryMonth":null, "expiryYear":null }, "timestamp":"2023-07-20T11:12:26.510635Z", "customer":{ "givenName":"Grace", "surname":"Nkosi", "merchantCustomerId":null, "sex":"", "mobile":null, "email":null, "status":null, "phone":null }, "shipping":{ "street1":null, "street2":null, "city":null, "country":null, "state":null, "postcode":null, "company":null }, "billing":{ "street1":null, "street2":null, "city":null, "sex":"", "country":null, "state":null, "postcode":null, "company":null }, "shopify":{ "orderId":null, "accountId":null, "signature":null, "testMode":null }, "bankAccount":{ "holder":null, "bankName":null, "bankCode":null }, "recon":{ "authCode":null, "ciMerchantNumber":null, "resultCode":null, "rrn":null, "stan":null }, "customParameters":{ "PEACH_MERCHANT_ID":"e098a59e50e411eb88ef02de7a5a0a6z" } } ``` -------------------------------- ### Peach EFT Testing Source: https://developer.peachpayments.com/docs/reference-test-and-go-live Instructions for testing Peach EFT in the sandbox environment using the Payments API. Involves selecting 'SIMULATOR' in the bank selector. ```APIDOC ## Peach EFT Testing ### Description Test Peach EFT in the Payments API by using the simulator in the sandbox environment. When the bank selector user interface appears, click **SIMULATOR**, select the desired status, and click **Continue**. ``` -------------------------------- ### Query Checkout Status with cURL Source: https://developer.peachpayments.com/docs/checkout-payment-flow This cURL command shows how to query the status of a Peach Payments checkout transaction from the command line. It sends a GET request to the status endpoint, including the necessary authentication, transaction ID, and signature parameters in the URL. ```curl curl --location --request GET 'https://testsecure.peachpayments.com/status?authentication.entityId=8ac7a4c8708b8dae01708be6bb3b018e&merchantTransactionId=ffghfsdrererwsdsf&signature=99699bb4a04af65a762ec4d15363a3d79aa21a12786721e0e89fa6c98933fb18' ``` -------------------------------- ### Query Checkout Status with Python Source: https://developer.peachpayments.com/docs/checkout-payment-flow This Python script demonstrates how to query the status of a Peach Payments checkout transaction using the requests library. It makes a GET request to the status endpoint, requiring authentication details and a merchantTransactionId. The response text is printed to the console. ```python import requests url = "https://testsecure.peachpayments.com/status?authentication.entityId=8ac7a4c8708b8dae01708be6bb3b018e&merchantTransactionId=ffghfsdrererwsdsf&signature=99699bb4a04af65a762ec4d15363a3d79aa21a12786721e0e89fa6c98933fb18" payload = {} headers= {} response = requests.request("GET", url, headers=headers, data = payload) print(response.text.encode('utf8')) ``` -------------------------------- ### ZeroPay Testing Source: https://developer.peachpayments.com/docs/reference-test-and-go-live Details for testing ZeroPay in the sandbox environment, including test ID number, OTP, and minimum amount. ```APIDOC ## ZeroPay Testing ### Description Use the following details to test ZeroPay in the sandbox environment. ### Test Details * **ID number:** `9512235170089` * **OTP:** `00000` * **Amount:** R30 or more ``` -------------------------------- ### Float Testing Source: https://developer.peachpayments.com/docs/reference-test-and-go-live Instructions for testing Float in the sandbox environment using the Payments API. Includes custom parameters for test mode and test card details. ```APIDOC ## Float Testing ### Description To test Float against a simulator in the sandbox environment, include `"customParameters[enableTestMode]":"true"` in the Payments API request body. This is not required when testing in Checkout. ### Test Card Details * **Card number:** `5200000000000023` * **CVV:** Any three digits * **Expiry date:** Any future date ``` -------------------------------- ### GET /api/payments Source: https://developer.peachpayments.com/docs/retrieve-all-payment-links Retrieve all payment links for a merchant. This endpoint allows querying merchant transactions to get all payment links and their statuses. The response can be in JSON or CSV format. ```APIDOC ## GET /api/payments ### Description Retrieve a list of all payment links associated with a merchant account. This endpoint is useful for monitoring payment statuses and for data export purposes. The response format can be specified using the `Accept` header. ### Method GET ### Endpoint `/api/payments` ### Parameters #### Query Parameters - **limit** (integer) - Optional - The maximum number of payment links to return. - **offset** (integer) - Optional - The number of payment links to skip before starting to collect the result set. #### Headers - **Authorization** (string) - Required - Bearer token for authentication. - **Accept** (string) - Optional - Specifies the desired response format. Defaults to `application/json`. Use `text/csv` to export to CSV. ### Request Example ```bash curl -X GET \ 'https://links.peachpayments.com/api/payments?limit=10&offset=0' \ -H 'Authorization: Bearer YOUR_BEARER_TOKEN' \ -H 'Accept: application/json' ``` ### Response #### Success Response (200) - **payments** (array) - A list of payment link objects, each containing details such as ID, status, amount, and creation date. - **pagination** (object) - Information about the pagination of the results. #### Response Example (JSON) ```json { "payments": [ { "id": "pl_12345abcde", "status": "PAID", "amount": 100.50, "currency": "ZAR", "createdAt": "2023-10-27T10:00:00Z", "expiresAt": "2023-11-27T10:00:00Z" } ], "pagination": { "limit": 10, "offset": 0, "total": 50 } } ``` #### Response Example (CSV) ```csv ID,Status,Amount,Currency,CreatedAt,ExpiresAt pl_12345abcde,PAID,100.50,ZAR,2023-10-27T10:00:00Z,2023-11-27T10:00:00Z ``` ``` -------------------------------- ### Example POST Redirect Request for Scan to Pay Source: https://developer.peachpayments.com/docs/payments-api-flows This example shows a POST request for Scan to Pay redirects, including Content-Type header and form-urlencoded data parameters such as amount, connector, currency, and transaction. ```curl curl --location 'https://testapi-v2.peachpayments.com/verify/' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'amount=10.00' \ --data-urlencode 'connector=MASTERPASS' \ --data-urlencode 'currency=ZAR' \ --data-urlencode 'transaction=867acdb32cd1451eb5a4b9bb3ac1994z' ``` -------------------------------- ### POST /checkout/initiate Source: https://developer.peachpayments.com/docs/checkout-payment Initiates a checkout process, typically used for redirect-based checkouts. This endpoint requires a set of parameters to define the transaction details, customer information, billing and shipping addresses, and cart details. ```APIDOC ## POST /checkout/initiate ### Description Initiates a checkout process, typically used for redirect-based checkouts. This endpoint requires a set of parameters to define the transaction details, customer information, billing and shipping addresses, and cart details. ### Method POST ### Endpoint https://testsecure.peachpayments.com/checkout/initiate ### Parameters #### Query Parameters - **authentication.entityId** (string) - Required - The unique entity ID for authentication. - **signature** (string) - Required - The signature generated for the transaction data. - **merchantTransactionId** (string) - Required - A unique identifier for the transaction from the merchant's system. - **amount** (string) - Required - The transaction amount. - **paymentType** (string) - Required - The type of payment (e.g., 'DB' for debit). - **currency** (string) - Required - The currency code for the transaction (e.g., 'ZAR'). - **nonce** (string) - Required - A unique, one-time-use string to prevent replay attacks. - **shopperResultUrl** (string) - Required - The URL to redirect the shopper to after the checkout process is completed. - **defaultPaymentMethod** (string) - Optional - The default payment method to be pre-selected (e.g., 'CARD'). - **forceDefaultMethod** (boolean) - Optional - Forces the default payment method, preventing shopper selection. - **merchantInvoiceId** (string) - Optional - The merchant's invoice ID. - **customParameters[example]** (string) - Optional - A key-value pair for custom parameters. - **customer.merchantCustomerId** (string) - Optional - The merchant's customer ID. - **customer.givenName** (string) - Optional - The customer's first name. - **customer.surname** (string) - Optional - The customer's last name. - **customer.mobile** (string) - Optional - The customer's mobile number. - **customer.email** (string) - Optional - The customer's email address. - **customer.status** (string) - Optional - The customer's status. - **customer.birthDate** (string) - Optional - The customer's date of birth (YYYY-MM-DD). - **customer.ip** (string) - Optional - The customer's IP address. - **customer.phone** (string) - Optional - The customer's phone number. - **billing.street1** (string) - Optional - The first line of the billing street address. - **billing.street2** (string) - Optional - The second line of the billing street address. - **billing.city** (string) - Optional - The billing city. - **billing.company** (string) - Optional - The billing company name. - **billing.country** (string) - Optional - The billing country code (e.g., 'ZA'). - **billing.state** (string) - Optional - The billing state or province. - **billing.postcode** (string) - Optional - The billing postal code. - **shipping.street1** (string) - Optional - The first line of the shipping street address. - **shipping.street2** (string) - Optional - The second line of the shipping street address. - **shipping.city** (string) - Optional - The shipping city. - **shipping.company** (string) - Optional - The shipping company name. - **shipping.postcode** (string) - Optional - The shipping postal code. - **shipping.country** (string) - Optional - The shipping country code (e.g., 'ZA'). - **shipping.state** (string) - Optional - The shipping state or province. - **cart.tax** (string) - Optional - The tax amount for the cart. - **cart.shippingAmount** (string) - Optional - The shipping amount for the cart. - **cart.discount** (string) - Optional - The discount amount for the cart. - **createRegistration** (boolean) - Optional - Whether to create a shopper registration. - **notificationUrl** (string) - Optional - The URL for transaction notifications. - **cancelUrl** (string) - Optional - The URL to redirect the shopper to if the transaction is cancelled. ### Request Example ```curl curl --location -g --request POST 'https://testsecure.peachpayments.com/checkout/initiate' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Accept: application/json' \ --header 'Referer: https://example.com' \ --data-urlencode 'authentication.entityId=8ac7a4ca68c22c4d0168c2caab2e0025' \ --data-urlencode 'signature=311ed8e11e2da00d98c7479ca390a5396fe643e13629d850243dada877963afd' \ --data-urlencode 'merchantTransactionId=Test1234' \ --data-urlencode 'amount=100.00' \ --data-urlencode 'paymentType=DB' \ --data-urlencode 'currency=ZAR' \ --data-urlencode 'nonce=JHGJSGHDSKJHGJDHGJH' \ --data-urlencode 'shopperResultUrl=https://example.com' \ --data-urlencode 'defaultPaymentMethod=CARD' \ --data-urlencode 'forceDefaultMethod=false' \ --data-urlencode 'merchantInvoiceId=Test1234' \ --data-urlencode 'customParameters[example]=example' \ --data-urlencode 'customer.merchantCustomerId=0001' \ --data-urlencode 'customer.givenName=John' \ --data-urlencode 'customer.surname=Smith' \ --data-urlencode 'customer.mobile=0712345678' \ --data-urlencode 'customer.email=johnsmith@example.com' \ --data-urlencode 'customer.status=NEW' \ --data-urlencode 'customer.birthDate=1999-01-01' \ --data-urlencode 'customer.ip=192.168.1.1' \ --data-urlencode 'customer.phone=0212345678' \ --data-urlencode 'billing.street1=1 Example Road' \ --data-urlencode 'billing.street2=LocalityA' \ --data-urlencode 'billing.city=Cape Town' \ --data-urlencode 'billing.company=CompanyA' \ --data-urlencode 'billing.country=ZA' \ --data-urlencode 'billing.state=Western Cape' \ --data-urlencode 'billing.postcode=7000' \ --data-urlencode 'shipping.street1=1 Example Road' \ --data-urlencode 'shipping.street2=LocalityA' \ --data-urlencode 'shipping.city=Cape Town' \ --data-urlencode 'shipping.company=CompanyA' \ --data-urlencode 'shipping.postcode=7000' \ --data-urlencode 'shipping.country=ZA' \ --data-urlencode 'shipping.state=Western Cape' \ --data-urlencode 'cart.tax=15.00' \ --data-urlencode 'cart.shippingAmount=12.25' \ --data-urlencode 'cart.discount=02.25' \ --data-urlencode 'createRegistration=false' \ --data-urlencode 'notificationUrl=' \ --data-urlencode 'cancelUrl=' ``` ### Response #### Success Response (200) - **redirectUrl** (string) - The URL to redirect the shopper to for completing the payment. #### Response Example ```json { "redirectUrl": "https://testsecure.peachpayments.com/checkout/redirect?id=some_checkout_id" } ``` ``` -------------------------------- ### Webhook Payload Examples (JSON) Source: https://developer.peachpayments.com/docs/payouts-api-1 Examples of webhook payloads sent by the Payouts API for different payout statuses. These payloads contain information about the merchant, payout status, timestamps, and relevant codes. The 'Failed' event includes an error object with details. ```json { "merchantId": "5fb59f82d6fa11ef9b3002f694e28f55", "status": "processing", "lastUpdated": "2025-07-02T11:00:04.352Z", "payoutId": "d3e31e2d-4f50-49f7-b89f-fd3f0b3642bb", "resultCode": "2900.000.003" } ``` ```json { "merchantId": "5fb59f82d6fa11ef9b3002f694e28f55", "status": "successful", "lastUpdated": "2025-07-02T11:00:45.406Z", "payoutId": "ae3be0f1-40d1-4b28-8072-6f78d4493444", "resultCode": "2000.000.000" } ``` ```json { "merchantId": "5fb59f82d6fa11ef9b3002f694e28f55", "status": "failed", "lastUpdated": "2025-07-02T11:00:04.566Z", "payoutId": "30ce5525-7de5-492d-a147-15592b14b266", "resultCode": "2001.002.106", "error": { "title": "Payout processing error", "message": "There is no account associated with the account number and the bank you entered. Double-check your input and try again.", "code": "2001.002.106" } } ``` -------------------------------- ### Capitec Pay Testing Source: https://developer.peachpayments.com/docs/reference-test-and-go-live Instructions for testing Capitec Pay in the sandbox environment using the Payments API. Includes custom parameters for test mode and specific ID/phone numbers for various scenarios. ```APIDOC ## Capitec Pay Testing ### Description To test Capitec Pay against a simulator in the sandbox environment, include `"customParameters[enableTestMode]":"true"` in the Payments API request body. This is not required when testing in Checkout. **Note:** High-risk merchants must provide verified ID numbers that the customer cannot edit and cannot offer the phone number option. ### Test Scenarios **Payment Request Scenarios:** | Scenario | ID number | Phone number | Result code | | :--------------------------------------- | :-------------- | :----------- | :------------ | | Client not registered on the banking app | `1111111111106` | `0111111106` | `000.400.102` | | Default transaction limit exceeded | `1111111111109` | `0111111109` | `800.100.162` | | Consent request created successfully | `1111111111190` | `0111111190` | `000.200.000` | **Transaction Status Scenarios:** | Scenario | ID number | Phone number | Result code | | :----------------------------------------------- | :-------------- | :----------- | :------------------------------------------------- | | Payment consent declined by client | `1111111111137` | `0111111137` | `100.396.101`: Does not appear in Dashboard | | Payment consent request timed out | `1111111111138` | `0111111138` | `900.100.400` | | Payment failed | `1111111111139` | `0111111139` | `800.100.100` | | Client reported payment consent request as fraud | `1111111111140` | `0111111140` | `000.100.220` | | Payment successful | `1111111111214` | `01111111214`| `000.100.110` in sandbox and `000.000.000` in live | **Note:** To execute tests against actual endpoints, contact support. This requires manual intervention and synchronization between you, Peach Payments, and Capitec. ``` -------------------------------- ### Generate HMAC SHA256 Signature in TypeScript Source: https://developer.peachpayments.com/docs/checkout-authentication This TypeScript code generates an HMAC SHA256 signature using the CryptoJS library. It takes a message string and a secret key to produce a hexadecimal hash, which is essential for verifying the integrity of Peach Payments requests. Ensure `crypto-js` is installed (`npm install crypto-js`). ```typescript import CryptoJS from "crypto-js"; const secret = "3fcd7cf22f55119eadbe02d14de18c0c"; const message = "amount2authentication.entityId8ac7a4ca68c22c4d0168c2caab2e0025currencyZARdefaultPaymentMethodCARDmerchantTransactionIdTest1234nonceJHGJSGHDSKJHGJDHGJHpaymentTypeDBshopperResultUrlhttps://example.com/example-webhook"; const signature = CryptoJS.HmacSHA256(message, secret).toString(CryptoJS.enc.Hex); console.log(signature); ``` -------------------------------- ### Get Checkout Status Source: https://developer.peachpayments.com/docs/v2-checkout-hosted Retrieve the status of a specific checkout transaction using its unique checkout ID. ```APIDOC ## GET /v2/checkout/{checkoutId}/status ### Description Retrieves the status of a previously created checkout transaction. ### Method GET ### Endpoint `{checkout-endpoint}/v2/checkout/{checkoutId}/status` ### Parameters #### Path Parameters - **checkoutId** (string) - Required - The unique identifier of the checkout transaction. #### Query Parameters - **authorization** (string) - Required - The Bearer token obtained from the `/api/oauth/token` endpoint. ### Response #### Success Response (200) - **checkoutId** (string) - The unique identifier for the checkout transaction. - **status** (string) - The current status of the checkout (e.g., 'PENDING', 'SUCCESS', 'FAILED'). - **result** (string) - The result code of the transaction. - **description** (string) - A description of the transaction result. ``` -------------------------------- ### Share Payment Page with Prepopulated Values (URL Parameters) Source: https://developer.peachpayments.com/docs/payment-page Construct a shareable payment page link with prepopulated fields like amount, reference, email, first name, last name, and mobile number. These parameters are appended as a query string to the base payment page URL. Ensure all provided parameters are valid and that the relevant customer information collection toggles are enabled in the Payment Page settings if prepopulating fields like email or name. ```URL https://page.peachpayments.com/peach-p?amount=10.00&reference=INV12345678&email=grace.nkosi@example.com&firstName=Grace&lastName=Nkosi&mobile=0123456789 ``` -------------------------------- ### GET /api/payments/{paymentId} Source: https://developer.peachpayments.com/docs/query-payment Query the status of a specific payment transaction using its unique payment ID. ```APIDOC ## GET /api/payments/{paymentId} ### Description Queries the status of a payment transaction. This endpoint returns the payment details and its current status (initiated, processing, completed, cancelled, expired). ### Method GET ### Endpoint /api/payments/{paymentId} ### Parameters #### Path Parameters - **paymentId** (string) - Required - The unique identifier of the payment transaction. #### Query Parameters None #### Request Body None ### Request Example (No request body for GET requests, authentication typically handled via headers) ### Response #### Success Response (200) - **paymentId** (string) - The unique identifier of the payment. - **status** (string) - The current status of the payment (e.g., 'completed', 'processing'). - **amount** (number) - The amount of the payment. - **currency** (string) - The currency of the payment. #### Response Example ```json { "paymentId": "f0c711a3-787b-44d7-8417-f3425a107273", "status": "completed", "amount": 100.50, "currency": "ZAR" } ``` ```