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

  1. Customer request a service
  2. Charging a customer after a service is fulfilled 
  3. Cancelling a service
  4. Requesting a service for the second time (Customer with stored card)
  5. 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=="