Preauthorization & Capture
Preauthorization
Preauthorization, also known as "pre-authorization" or "funds hold," is a crucial stage in transaction processing. During this phase, the availability of funds in the cardholder's account is verified before completing the transaction. Its main objective is to reserve a certain amount of funds in the cardholder's account to ensure that there is sufficient balance available to cover the future transaction.
Preauthorization is widely used in situations where it is necessary to ensure the availability of funds before delivering a product or service. For example, in e-commerce, it can be used to ensure that the card balance is sufficient before shipping an item or making a reservation.
Implementation of the pre-authorization
Requirements
Before proceeding with the implementation of the pre-authorization, please make sure you have the following requirements:
Step 1. Generate an acceptance token.
Step 2. Tokenize the payment method (Card).
Step 3. Before creating the pre-authorization, please consider the following:
-
You can create a payment source to store the cardholder's data for future pre-authorizations or payments. View process.
-
Alternatively, you can skip the creation of the payment source and proceed directly to creating the pre-authorization. View process.
Step 4. Please remember that creating the pre-authorization requires the use of your private key, which should be sent as a Bearer token:
- If you want to create a pre-authorization with a payment source, you need to generate the acceptance token again and make a
POST /payment_sourcesrequest with the following JSON body:
{
"type": "CARD",
"payment_source_id": 297, // Payment source ID
"customer_email": "prueba@test.com", // Cardholder's email
"financial_operation": "PREAUTHORIZATION",
"acceptance_token": "acceptance_token", // Acceptance token
"data": {
"amount_in_cents": 100, // Pre-authorization amount
"currency": "USD"
}
}
- On the other hand, if you want to create a pre-authorization directly, you should make a
POST /payment_sourcesrequest with the following JSON body:
{
"type": "CARD",
"customer_email": "prueba@test.com", // Cardholder's email
"financial_operation": "PREAUTHORIZATION",
"token": "token_card", // Token of the tokenized card
"acceptance_token": "acceptance_token", // Acceptance token
"data": {
"amount_in_cents": 100, // Pre-authorization amount
"currency": "USD"
}
}
You will receive the following JSON response:
{
"data": {
"id": 335,
"public_data": {
"type": "CARD",
"financial_operation": "PREAUTHORIZATION",
"amount_in_cents": 100,
"number_of_installments": 1,
"currency": "USD"
},
"token": "tok_devtest_196_8A7308f20c2d236f42252972390b4eb1",
"type": "CARD",
"status": "PROCESSING",
"customer_email": "prueba@test.com"
}
}
Step 5. Perform periodic queries to check the status of the pre-authorization and ensure its successful execution:
To query the pre-authorization, make a GET /payment_sources/:id request. Don't forget to include your private key as the Bearer token. You will receive the following JSON response:
{
"data": {
"id": 335,
"public_data": {
"type": "CARD",
"financial_operation": "PREAUTHORIZATION",
"amount_in_cents": 100,
"number_of_installments": 1,
"currency": "USD"
},
"token": "tok_devtest_196_8A7308f20c2d236f42252972390b4eb1",
"type": "CARD",
"status": "PENDING",
"customer_email": "jmtm141097@gmail.com",
"extra": {
"three_ds_auth": {
"current_step": "BROWSER_INFO", // Refers to the authentication type: (BROWSER_INFO - CHALLENGE)
"current_step_status": "PENDING",
"three_ds_method_data": "<iframe id="tdsMmethodTgtFrame" name="tdsMmethodTgtFrame" style="visibility: hidden; width: 1px; height: 1px;" xmlns="http://www.w3.org/1999/xhtml"><!--.--></iframe><form id="tdsMmethodForm" name="tdsMmethodForm" action="https://api-sandbox.pa.dev.wompi.dev/v1/webhook_events/acs_response?order_id=PAYMENT_SOURCE-335" method="post" target="tdsMmethodTgtFrame" xmlns="http://www.w3.org/1999/xhtml"><input type="hidden" name="operation" value="CHALLENGE_IFRAME_BIN" /><script type="text/javascript">document.getElementById("tdsMmethodForm").submit();</script></form>"
}
}
}
}
Step 6. Render the IFRAME to continue with the authentication process:
In the pre-authorization response, the extra key contains relevant additional information. Specifically, we will focus on the three_ds_method_data key, which includes an HTML code snippet. This is an IFRAME block that should be integrated and displayed on the page to securely proceed with the card authentication process. Additionally, you will also find the current_step key, which indicates the current state of authentication and may refer to the specific type of authentication required to verify the cardholder's identity.
Step 7. Don't forget to perform periodic inquiries on the pre-authorization.
This is how a successful pre-authorization looks like and is ready to be captured:
{
"data": {
"id": 335,
"public_data": {
"type": "CARD",
"financial_operation": "PREAUTHORIZATION",
"amount_in_cents": 100,
"number_of_installments": 1,
"currency": "USD"
},
"token": "tok_devtest_196_8A7308f20c2d236f42252972390b4eb1",
"type": "CARD",
"status": "AVAILABLE",
"customer_email": "jmtm141097@gmail.com",
"extra": {
"three_ds_auth": {
"current_step": "AUTHENTICATION",
"current_step_status": "COMPLETED"
}
}
}
}
Capture
Capture is the stage where the final charge or transfer of funds reserved during the preauthorization takes place. Once the transaction is completed or the agreed-upon condition is met, a capture request is sent to obtain the funds that were reserved during the preauthorization. This results in the transfer of funds from the cardholder's account to the business or service provider. Capture is crucial for concluding the transaction and ensuring that the business receives the corresponding payment.
Implementation of Capture
Requirements
Before performing a capture, make sure you have the following requirements:
-
Have a pre-authorization in the
AVAILABLEstate.
Step 1. Create a transaction.
To proceed with the capture process, we need to send a POST /transactions request. In the request headers, we should include the private key of our business as a Bearer token. Additionally, we need to send the following JSON as the request body:
{
"amount_in_cents": 100, // Capture amount (should not exceed the pre-authorized amount)
"public_key": "pub_prod_ffhas23932", // Merchant's public key
"currency": "USD",
"customer_email": "prueba@test.com",
"reference": "TEST34502", // Unique transaction reference
"payment_source_id": 298 // Payment source ID (pre-authorization)
}
Step 2. Perform periodic inquiries of the transaction to verify its status and ensure its successful execution.
This is how a successful capture looks like:
{
"data": {
"id": "1196-1689602000-65841",
"created_at": "2023-07-17T13:53:24.308Z",
"amount_in_cents": 100,
"reference": "TEST34502",
"currency": "USD",
"payment_method_type": "CARD",
"payment_method": {
"type": "CARD",
"extra": {
"name": "VISA-0031",
"type": "CAPTURE", // Indicates that the transaction is a capture
"brand": "VISA",
"last_four": "0031",
"is_three_ds": false,
"three_ds_auth": null,
"external_identifier": "QtcGZjh9nX",
"processor_response_code": "00"
}
},
"redirect_url": null,
"status": "APPROVED", // Final status of the transaction
"status_message": null,
"merchant": {
"name": "Pruebas SandBox",
"legal_name": "Pruebas SandBox",
"contact_name": "Pepito Perez",
"phone_number": "+50732345634",
"logo_url": null,
"legal_id_type": "RUC",
"email": "prueba@test.com",
"legal_id": "2452345-5"
},
"taxes": []
}
}
