--- title: "Payment" method: POST path: "/payments" tags: ["Payment or refund"] --- # Payment `POST /payments` ## Request - Base URL: `https://testapi-v2.peachpayments.com` - URL: `https://testapi-v2.peachpayments.com/payments` - Auth: none declared Initiate a debit transaction. Certain parameters are required for specific payment methods and certain parameters act differently depending on the payment method. - For PayShap, `virtualAccount.bank` (the customer's bank: `FIRSTNATIONALBANK`, `DISCOVERYBANK`, `NEDBANK`, `TYMEBANK`, or `ABSABANK`), `virtualAccount.type` (the customer's identifier type: `CELLPHONE`), `virtualAccount.accountId` (the customer's phone number in the `+27-123456789` format), and `shopperResultUrl` are required. - For Capitec Pay, `virtualAccount.type` (the customer's identifier type: `IDNUMBER`, `CELLPHONE`, or `ACCOUNTNUMBER`), `virtualAccount.accountId` (the customer's 13-digit ID number, 10-digit phone number starting with `0`, or up to 64-digit, alphanumeric bank account number), and `shopperResultUrl` are required. High-risk merchants must provide the verified `IDNUMBER` and cannot use the `CELLPHONE` or `ACCOUNTNUMBER` account types. - For Peach EFT, the `shopperResultUrl` is required. Absa categorises merchants as either low risk or high risk. Low-risk merchants support paying with ID; high-risk merchants must supply a merchant-verified ID that the customer cannot edit. For high-risk merchants using the Payments API, supply the verified ID in `virtualAccount` as an array. - For 1Voucher, `customer.mobile` (the customer's phone number for receiving change vouchers and refunds) and `virtualAccount.password` (the voucher PIN) are required. - For Mobicred, `virtualAccount.accountId` (the customer's Mobicred email address), `virtualAccount.password` (the customer's Mobicred password), and `shopperResultUrl` are required. - For RCS cards, `card.number` (the customer's RCS card number) and `shopperResultUrl` are required. - For M-PESA, `virtualAccount.accountId` (the customer's 12-digit phone number) and `shopperResultUrl` are required. M-PESA only accepts integer amounts, not decimals, so round up your amount. - For blink by Emtel and MCB Juice, `virtualAccount.accountId` (the customer's 8-digit phone number) and `shopperResultUrl` are required. - For Payflex, ZeroPay, Float, Happy Pay, Scan to Pay, MoneyBadger, and MauCAS, the `shopperResultUrl` is required. For more information, see the [documentation](https://developer.peachpayments.com/docs/payments-api-flows#payment-flow), and for sample calls, see our [public Postman collection](https://www.postman.com/peachpayments/peach-payments-public-workspace/request/yblmbqd/payments-public?action=share&creator=20323380&ctx=documentation&active-environment=13324425-9345d747-fcdd-4a5c-83e4-6f637771b28b). ## Request body - PaymentRequest: Initiate a debit transaction. - `authentication` Authentication, required: Authenticate requests using the userId, password, and entityId. - `userId` string, required: Authentication userId. - `password` string, required: Authentication password. - `entityId` string, required: Authentication entityId - `merchantTransactionId` string, required: Merchant-provided reference number, often used for reconciliation. - `amount` string, required: The payment request amount. - `currency` string, iso-4217, required: The currency code of the payment request amount as defined by ISO-4217. - `paymentBrand` 'PAYFLEX' | 'ZEROPAY' | '1FORYOU' | 'MASTERPASS' | 'MPESA' | 'BLINKBYEMTEL' | 'MOBICRED' | 'CAPITECPAY' | 'PEACHEFT' | 'MCBJUICE' | 'RCS' | 'FLOAT' | 'HAPPYPAY' | 'MAUCAS' | 'MONEYBADGER' | 'PAYSHAP', required: The payment brand specifies the method of payment for the request. - `paymentType` 'DB' | 'RF', required: Payment type of the transaction. See the [payment methods documentation](https://developer.peachpayments.com/docs/pp-payment-methods#south-africa) for details on which payment methods support the RF payment type. - `virtualAccount` union - VirtualAccount: The virtual account object. - `accountId` string: The account ID. - `password` string: The virtual account password. - `token` string: The virtual account token. - `type` 'CELLPHONE' | 'IDNUMBER' | 'ACCOUNTNUMBER': The virtual account type. - `bank` 'FIRSTNATIONALBANK' | 'DISCOVERYBANK' | 'NEDBANK' | 'TYMEBANK' | 'ABSABANK': The virtual account bank. Only applicable to PayShap. - VirtualAccountProcessor[]: Applicable for `PEACHEFT`. Array of processor-based virtual account entries. - `processor` 'ABSAEFT', required: The payment processor identifier. - `identifier` object[], required: A list of customer identifiers required by the processor. - `type` 'IDNUMBER', required: The identifier type. - `accountId` string, required: The customer's identifier value. For IDNUMBER, this is the customer's 13-digit South African ID number. - `shipping` Address: Optional object that can be used for billing or shipping information. - `city` string: The town, district, or city linked to billing or shipping. - `company` string: The customer's company name. - `country` string, iso-3166-1 alpha-2: The country linked to billing or shipping as defined by ISO-3166-1 alpha-2. - `houseNumber1` string: Primary house number of the billing or shipping address. - `postcode` string: The postal code or zip code of the billing or shipping address. - `state` string: The county, state, or region of the billing address. - `street1` string: The door number, floor, building number, building name, and/or street name of the billing or shipping address. - `street2` string: Secondary house number of the billing or shipping address. Used when more addresses are bundled to the same primary house number. If present, houseNumber1 is required. - `customer` Customer: Optional object sent if customer data is required. - `email` string, email: The customer's email address. - `fax` string: The customer's fax number, if provided. - `givenName` string: The customer's first name or given name. Peach Payments recommends including the name so that it displays in the Peach Dashboard and is available for subsequent queries. - `surname` string: The customer's last name or surname. Peach Payments recommends including the surname so that it displays in the Peach Dashboard and is available for subsequent queries. - `mobile` string: The customer's mobile phone number. - `phone` string: The customer's phone number. - `ip` string: The customer's IP address. - `merchantCustomerLanguage` string: The language used for the customer on the merchant's site. - `status` string: Used to determine if this is a new or returning customer. - `merchantCustomerId` string: The customer's ID on the merchant's site. - `taxId` string: The customer's tax ID, if required. - `taxType` string: The customer's tax type, if required. - `birthDate` string: The customer's birth date. - `browser` object: The customer's browser details. - `acceptHeader` string: The value of the accept header sent from the customer's browser. - `language` string: The value representing the browser language as defined in IETF BCP47. - `screenHeight` string: The total height of the customer's screen in pixels. - `screenWidth` string: The total width of the customer's screen in pixels. - `timezone` string: The time-zone offset in minutes between UTC and the local time of the customer's browser. - `userAgent` string: The exact content of the HTTP user-agent header. - `javaEnabled` string: The boolean that represents the ability of the customer's browser to execute Java. - `javascriptEnabled` string: The boolean that represents the ability of the customer's browser to execute JavaScript. - `screenColorDepth` string: The value representing the bit depth of the colour palette for displaying images in bits per pixel. - `challengeWindow` string: The dimensions of the challenge window that has been displayed to the customer. - `billing` Address: Optional object that can be used for billing or shipping information. - `city` string: The town, district, or city linked to billing or shipping. - `company` string: The customer's company name. - `country` string, iso-3166-1 alpha-2: The country linked to billing or shipping as defined by ISO-3166-1 alpha-2. - `houseNumber1` string: Primary house number of the billing or shipping address. - `postcode` string: The postal code or zip code of the billing or shipping address. - `state` string: The county, state, or region of the billing address. - `street1` string: The door number, floor, building number, building name, and/or street name of the billing or shipping address. - `street2` string: Secondary house number of the billing or shipping address. Used when more addresses are bundled to the same primary house number. If present, houseNumber1 is required. - `customer` Customer: Optional object sent if customer data is required. - `email` string, email: The customer's email address. - `fax` string: The customer's fax number, if provided. - `givenName` string: The customer's first name or given name. Peach Payments recommends including the name so that it displays in the Peach Dashboard and is available for subsequent queries. - `surname` string: The customer's last name or surname. Peach Payments recommends including the surname so that it displays in the Peach Dashboard and is available for subsequent queries. - `mobile` string: The customer's mobile phone number. - `phone` string: The customer's phone number. - `ip` string: The customer's IP address. - `merchantCustomerLanguage` string: The language used for the customer on the merchant's site. - `status` string: Used to determine if this is a new or returning customer. - `merchantCustomerId` string: The customer's ID on the merchant's site. - `taxId` string: The customer's tax ID, if required. - `taxType` string: The customer's tax type, if required. - `birthDate` string: The customer's birth date. - `browser` object: The customer's browser details. - `acceptHeader` string: The value of the accept header sent from the customer's browser. - `language` string: The value representing the browser language as defined in IETF BCP47. - `screenHeight` string: The total height of the customer's screen in pixels. - `screenWidth` string: The total width of the customer's screen in pixels. - `timezone` string: The time-zone offset in minutes between UTC and the local time of the customer's browser. - `userAgent` string: The exact content of the HTTP user-agent header. - `javaEnabled` string: The boolean that represents the ability of the customer's browser to execute Java. - `javascriptEnabled` string: The boolean that represents the ability of the customer's browser to execute JavaScript. - `screenColorDepth` string: The value representing the bit depth of the colour palette for displaying images in bits per pixel. - `challengeWindow` string: The dimensions of the challenge window that has been displayed to the customer. - `shopify` Shopify: The Shopify object. - `orderId` string: The Shopify order ID. - `accountId` string: The Shopify account ID. - `signature` string: The Shopify signature. - `testMode` string: Shopify test mode. - `customer` Customer: Optional object sent if customer data is required. - `email` string, email: The customer's email address. - `fax` string: The customer's fax number, if provided. - `givenName` string: The customer's first name or given name. Peach Payments recommends including the name so that it displays in the Peach Dashboard and is available for subsequent queries. - `surname` string: The customer's last name or surname. Peach Payments recommends including the surname so that it displays in the Peach Dashboard and is available for subsequent queries. - `mobile` string: The customer's mobile phone number. - `phone` string: The customer's phone number. - `ip` string: The customer's IP address. - `merchantCustomerLanguage` string: The language used for the customer on the merchant's site. - `status` string: Used to determine if this is a new or returning customer. - `merchantCustomerId` string: The customer's ID on the merchant's site. - `taxId` string: The customer's tax ID, if required. - `taxType` string: The customer's tax type, if required. - `birthDate` string: The customer's birth date. - `browser` object: The customer's browser details. - `acceptHeader` string: The value of the accept header sent from the customer's browser. - `language` string: The value representing the browser language as defined in IETF BCP47. - `screenHeight` string: The total height of the customer's screen in pixels. - `screenWidth` string: The total width of the customer's screen in pixels. - `timezone` string: The time-zone offset in minutes between UTC and the local time of the customer's browser. - `userAgent` string: The exact content of the HTTP user-agent header. - `javaEnabled` string: The boolean that represents the ability of the customer's browser to execute Java. - `javascriptEnabled` string: The boolean that represents the ability of the customer's browser to execute JavaScript. - `screenColorDepth` string: The value representing the bit depth of the colour palette for displaying images in bits per pixel. - `challengeWindow` string: The dimensions of the challenge window that has been displayed to the customer. - `cart` Cart: Customer cart data. - `cartItems` object[]: List of details of the items in the cart. - `name` string: The name of the item in the shopping cart. - `merchantItemId` string: The unique identifier of the item in the shopping cart. - `quantity` integer: The number of items in the shopping cart. - `price` string: The price of the item in the shopping cart. - `description` string: The description of the item in the shopping cart. - `weightInKg` number: The weight (in kg) of the item in the shopping cart. - `category` string: The category of the item in the shopping cart. - `tax` string: The tax percentage or amount applied to the price of the items in the shopping cart. - `shippingAmount` string: The payment request amount. - `discount` string: The discount percentage applied to the price of the items in the shopping cart. - `merchantInvoiceId` string: The merchant's invoice ID. - `shopperResultUrl` string, uri: The Payments API redirects the user to this URL after processing the payment request. ## Response `200` OK. - union - ErrorResponse: Error object describing the error. - `result` Result, required: The result object. - `code` string, required: The unique code that indicates the result status of the request. - `description` string, required - `resultDetails` ResultDetails: Additional details that can provide information about the status or result of the transaction. - `ExtendedDescription` string - `AcquirerResponse` string - `UserDisplayMessage` string - `timestamp` string, date-time, required: The timestamp of the transaction. - `id` string: The unique transaction ID provided by Peach Payments. - `paymentType` 'DB' | 'RF': Payment type of the transaction. See the [payment methods documentation](https://developer.peachpayments.com/docs/pp-payment-methods#south-africa) for details on which payment methods support the RF payment type. - `paymentBrand` 'PAYFLEX' | 'ZEROPAY' | '1FORYOU' | 'MASTERPASS' | 'MPESA' | 'BLINKBYEMTEL' | 'MOBICRED' | 'CAPITECPAY' | 'PEACHEFT' | 'MCBJUICE' | 'RCS' | 'FLOAT' | 'HAPPYPAY' | 'MAUCAS' | 'MONEYBADGER' | 'PAYSHAP': The payment brand specifies the method of payment for the request. - `customParameters` CustomParameters: A JSON object depicting custom information sent by the merchant. Echoed back in the response. - `amount` string: The payment request amount. - `currency` string, iso-4217: The currency code of the payment request amount as defined by ISO-4217. - PaymentResponse - `amount` string, required: The payment request amount. - `currency` string, iso-4217, required: The currency code of the payment request amount as defined by ISO-4217. - `paymentBrand` 'PAYFLEX' | 'ZEROPAY' | '1FORYOU' | 'MASTERPASS' | 'MPESA' | 'BLINKBYEMTEL' | 'MOBICRED' | 'CAPITECPAY' | 'PEACHEFT' | 'MCBJUICE' | 'RCS' | 'FLOAT' | 'HAPPYPAY' | 'MAUCAS' | 'MONEYBADGER' | 'PAYSHAP', required: The payment brand specifies the method of payment for the request. - `paymentType` 'DB' | 'RF', required: Payment type of the transaction. See the [payment methods documentation](https://developer.peachpayments.com/docs/pp-payment-methods#south-africa) for details on which payment methods support the RF payment type. - `result` Result, required: The result object. - `code` string, required: The unique code that indicates the result status of the request. - `description` string, required - `resultDetails` ResultDetails: Additional details that can provide information about the status or result of the transaction. - `ExtendedDescription` string - `AcquirerResponse` string - `UserDisplayMessage` string - `redirect` Redirect: The URL that the merchant must redirect the user to after the transaction has been created and is in a pending state. When the user is redirected, they can complete any actions required for that specific payment method. - `url` string, uri, required: The URL that the shopper must be redirected to in order to proceed. - `parameters` object[], required: Array of parameter names and values for the redirect URL. - `name` string - `value` string - `method` 'GET' | 'POST', required: REST method used for redirection. - `connectorTxID1` string: The unique transaction identifier provided by the payment service provider. - `connectorTxID2` string: Another unique transaction identifier provided by the payment service provider. - `customParameters` CustomParameters, required: A JSON object depicting custom information sent by the merchant. Echoed back in the response. - `timestamp` string, date-time, required: The timestamp of the transaction. - `id` string, required: The unique transaction ID provided by Peach Payments. - `merchantTransactionId` string: Merchant-provided reference number, often used for reconciliation. - `merchantInvoiceId` string: The merchant's invoice ID. - `shopperResultUrl` string, uri: The Payments API redirects the user to this URL after processing the payment request. - `virtualAccount` VirtualAccount: The virtual account object. - `accountId` string: The account ID. - `password` string: The virtual account password. - `token` string: The virtual account token. - `type` 'CELLPHONE' | 'IDNUMBER' | 'ACCOUNTNUMBER': The virtual account type. - `bank` 'FIRSTNATIONALBANK' | 'DISCOVERYBANK' | 'NEDBANK' | 'TYMEBANK' | 'ABSABANK': The virtual account bank. Only applicable to PayShap. - `transactionExpiryTimestamp` string, date-time: The expiry timestamp of the transaction. ## Other responses - `400`: Bad request. - `401`: Unauthorised. - `500`: Internal server error. --- [API](https://skmtc.dev/peachpayments/apis/payments-api.md) - [All operations](https://skmtc.dev/peachpayments/apis/payments-api/llms.txt) - [OpenAPI document](https://skmtc.dev/peachpayments/apis/payments-api/revisions/0b59022030e6?raw)