--- title: "Payment" method: POST path: "/payments" tags: ["Payment or refund"] --- # Payment `POST /payments` 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 Nedbank Direct EFT, 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' | 'NEDBANKDIRECTEFT', 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 - `message` string, required — A message describing the error. - `errors` object — A flattened map of errors that occurred with the input data. - 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' | 'NEDBANKDIRECTEFT', 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.net/peachpayments/apis/checkout.md) · [All operations](https://skmtc.net/peachpayments/apis/checkout/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/peachpayments/checkout/revisions/3a98165665f8/schema)