Pre-authorization (PA) and Capture(CP) Scenario : Peach Payments

A pre-authorization (PA) is a temporary hold on a customer's card transaction that typically lasts around 5 days (however, reservation period differs from bank to bank). We recommend cancelling any pre-authorization that will not be captured instead of allowing it to expire.

When you pre-authorize a card payment, you are verifying that sufficient funds exists on a customer's card before processing a sale.

When you create a pre-authorization, the cardholder's balance is reduced by the amount of the pre-authorization until the pre-authorization is captured or expires.

After pre-authorizing a payment, you may either capture (Debit) the payment or cancel it.

You capture a pre-authorized card payment when you are ready to process a payment for goods that you have shipped, or for goods or services that a customer has received.

Example scenario whereby a customer is charged after a merchant has fulfilled/completed a service requested by the customer

Customer request a service
Charging a customer after a service is fulfilled
Cancelling a service
Requesting a service for the second time (Customer with stored card)
Charging a customer after a service is fulfilled

1. Customer request a service
Use pre-authorisation(PA) paymentType instead of Debit(DB). A PA will reserve/hold funds until a capture request is sent to capture the held/reserved funds

a). Initial request

Generate checkout ID with the highlighted parameters included

curl https://eu-test.oppwa.com/v1/checkouts \
 -d "entityId=8a82xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
 -d "amount=10.00" \
 -d "currency=ZAR" \
 -d "paymentType=PA" \
 -d "standingInstruction.mode=INITIAL" \
 -d "standingInstruction.type=UNSCHEDULED" \
 -d "standingInstruction.source=CIT" \
 -d "createRegistration=true" \
 -H "Authorization: Bearer OGE4XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX=="

response:

{
  "result":{
    "code":"000.200.100",
    "description":"successfully created checkout"
  },
  "buildNumber":"7b78e08b0735d2f79db413b347a476b2b755e624@2021-10-01 10:59:24 +0000",
  "timestamp":"2021-10-05 15:25:10+0000",
  "ndc":"F652B9C56311AED2797980B8C4513ADC.uat01-vm-tx02",
  "id":"F652B9C56311AED2797980B8C4513ADC.uat01-vm-tx02"
}

b). Make a payment

Use the checkout ID in the HTML/ JavaScript widget to make payment

<html>
    
    <head><base target="_top"></head>
    <body> 
        
<form action="https://www.peachpayments.com" class="paymentWidgets" data-brands="VISA MASTER AMEX"></form>
        
<script src="https://eu-test.oppwa.com/v1/paymentWidgets.js?checkoutId=F652B9C56311AED2797980B8C4513ADC.uat01-vm-tx02"></script> 

    </body>
</html>

c). Get payment status request

Send a get payment status request to get a Token/Registration ID and ID/Unique ID

Token/Registration ID - use this parameter to charge stored cards
ID/Unique ID - use this parameter to capture and reverse a PA

curl -G https://eu-test.oppwa.com/v1/checkoutsF652B9C56311AED2797980B8C4513ADC.uat01-vm-tx02/payment \
 -d "entityId=8a82xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
 -H "Authorization: Bearer OGE4XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX=="

response

{
  "id":"8ac7a4a27c4df6d2017c5111c2b630d9",
  "registrationId":"8ac7a49f7c4df4d7017c5111c1fe4a57",
  "paymentType":"PA",
  "paymentBrand":"VISA",
  "amount":"1.00",
  "currency":"ZAR",
  "descriptor":"0840.6292.5376 Non3D_Channel",
  "recurringType":"INITIAL",
  "result":{
    "code":"000.100.110",
    "description":"Request successfully processed in 'Merchant in Integrator Test Mode'"
  },
  "card":{
    "bin":"411111",
    "binCountry":"US",
    "last4Digits":"1111",
    "holder":"test",
    "expiryMonth":"01",
    "expiryYear":"2022"
  },
  "customer":{
    "ip":"197.185.111.94",
    "ipCountry":"ZA"
  },
  "customParameters":{
    "StandingInstructionAPI":"true",
    "SHOPPER_EndToEndIdentity":"046d4f0267db22a83340734d8d667d641e38f99fb50f86f8152197bcebf0e0e7",
    "CTPE_DESCRIPTOR_TEMPLATE":"",
    "StoredCredentialType":"CIT",
    "StandingInstruction":"UNSCHEDULED"
  },
  "risk":{
    "score":"100"
  },
  "buildNumber":"7b78e08b0735d2f79db413b347a476b2b755e624@2021-10-01 10:59:24 +0000",
  "timestamp":"2021-10-05 15:28:10+0000",
  "ndc":"F652B9C56311AED2797980B8C4513ADC.uat01-vm-tx02",
  "standingInstruction":{
    "source":"CIT",
    "type":"UNSCHEDULED",
    "mode":"INITIAL"
  }
}

2. Charging a customer after a service is fulfilled

Send the following request to capture the PA (this will debit the reserved PA) - reference guide here: https://peachpayments.docs.oppwa.com/integrations/backoffice#capturePayment

curl https://eu-test.oppwa.com/v1/payments/8ac7a4a27c4df6d2017c5111c2b630d9/payments \
 -d "entityId=8a82xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
 -d "amount=10.00" \
 -d "currency=ZAR" \
 -d "paymentType=CP" \
 -H "Authorization:Bearer OGE4XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX=="

3. Cancelling a service

Send the following request to cancel service. Reference guide here: https://peachpayments.docs.oppwa.com/integrations/backoffice#reversal

curl https://eu-test.oppwa.com/v1/payments/8ac7a4a27c4df6d2017c5111c2b630d9 \
 -d "entityId=8a82xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
 -d "paymentType=RV" \
 -H "Authorization: Bearer OGE4XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX=="

4. Requesting a service for the second time (Customer with stored card)

Send a post request to the following endpoint with the highlighted parameters included "https://eu-test.oppwa.com/v1/registrations/{id}/payments \" as per the below request to charge the token/registration ID. Reference guide: https://peachpayments.docs.oppwa.com/tutorials/card-on-file

curl https://eu-test.oppwa.com/v1/registrations/8ac7a49f7c4df4d7017c5111c1fe4a57/payments \
 -d "entityId=8a82xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
 -d "amount=92.00" \
 -d "currency=ZAR" \
 -d "paymentType=PA" \
 -d "standingInstruction.mode=REPEATED" \
 -d "standingInstruction.type=UNSCHEDULED" \
 -d "standingInstruction.source=MIT" \
 -H "Authorization: Bearer OGE4XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX=="

Response

{
  "id":"8ac7a49f86e2255f0186e46baef47384",
  "paymentType":"PA",
  "amount":"92.00",
  "currency":"ZAR",
  "descriptor":"7636.1070.5034 Non3D_Channel ",
  "result":{
    "code":"000.100.110",
    "description":"Request successfully processed in 'Merchant in Integrator Test Mode'"
  },
  "resultDetails":{
    "ConnectorTxID1":"{E5516170-7BE4-4B99-91A2-A38D7E3E4426}",
    "ConnectorTxID2":"{ADE5D9F2-7CD0-431E-BA4E-2DA4EAC67D93}|7636.1070.5034",
    "AuthorisationCode":"952709",
    "AcquirerReference":"28383:04488506",
    "AcquirerResponse":"0"
  },
  "risk":{
    "score":"100"
  },
  "buildNumber":"b6f33dad3bf64e81948f1feb2209d7345029c9fc@2023-03-13 17:54:35 +0000",
  "timestamp":"2023-03-15 08:38:27+0000",
  "ndc":"8a8294174e735d0c014e78cf26461790_3efd8fa6c43d4f4882b9257623e514e8",
  "standingInstruction":{
    "source":"MIT",
    "type":"UNSCHEDULED",
    "mode":"REPEATED",
    "initialTransactionId":"{E5516170-7BE4-4B99-91A2-A38D7E3E4426}"
  }
}

5. Charging a customer after a service is fulfilled

Send the following request to capture the PA (this will debit the reserved PA) - reference guide here: https://peachpayments.docs.oppwa.com/integrations/backoffice#capture

curl https://eu-test.oppwa.com/v1/payments/8ac7a49f86e2255f0186e46baef47384/payments \
 -d "entityId=8a82xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
 -d "amount=92.00" \
 -d "currency=ZAR" \
 -d "paymentType=CP" \
 -H "Authorization:Bearer OGE4XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX=="

Pre-authorization (PA) and Capture(CP) Scenario Print

Related Articles