Advanced capture
This is often useful when the amount to capture is not accurately known at the time the authorization is issued.
In such situations, you:
- Authorize an amount to capture up to 7 days later.
- Create one or more payins against that authorization without exceeding the total authorized amount.
Any remaining funds are automatically freed up after 7 days.
This feature is only available with some paymentProducts.
Prerequisites – Steps to do before the authorization:
- Tokenize the card
- Create a Topup Card to associate with the user (if needed)
Authorize an amount
To authorize an amount, use the following endpoint which accepts the same payload as the direct capture.
bash
curl -X POST {baseUrl}/v1/topups/cards/authorizations \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
-d '{payload}'Here is a {payload} example:
json
{
"amount": 20,
"currency": "EUR",
"walletId": "{{walletId}}",
"userId": "{{userId}}",
"paymentProduct": "visa",
"topupCardId": "{{topupCardId}}",
"messageToUser": "string",
"acceptUrl": "acceptURL",
"declineUrl": "declineURL",
"pendingUrl": "pendingURL",
"exceptionUrl": "exceptionURL",
"cancelUrl": "cancelURL",
"eci": "9",
"authenticationIndicator": "2",
"orderId": "{{order_Id}}", // According to best practices
"description": "string",
"deviceChannel": 0,
"browserInfo": {
"javaEnabled": true,
"javascriptEnabled": true,
"ipaddr": "0.0.0.0",
"httpAccept": "string",
"httpUserAgent": "string",
"language": "string",
"colorDepth": 8, // Can be: 1, 4, 8, 15, 16, 32, 48
"screenHeight": 0,
"screenWidth": 0,
"timezone": "string",
"deviceFingerprint": "string"
},
"firstname": "Alex",
"lastname": "Oak",
"email": "aoak@example.com",
"phone": "string",
"streetAddress": "string",
"city": "string",
"zipCode": "string",
"country": "string",
"cardHolder": "A Oak"
}Returns the Authorization and sends an authorization.create webhook which contains the authorization UUID necessary to create payin(s) in the next step.
json
{
"authorizations": [
{
"authorizationId": "6de434ff-d2c5-511f-820c-6748385f2b42",
"userId": "100655503",
"walletId": "3152544",
"userFirstname": "Alex",
"walletEventName": "Main Account",
"walletAlias": "main-account-669f5b8e1e9cf",
"userLastname": "Oak",
"messageToUser": "The financial institution has approved the payment.",
"authorizationStatus": "PENDING",
"paymentMethodId": "25",
"amount": 20,
"currency": "EUR",
"createdDate": "",
"codeStatus": "150116",
"informationStatus": "Authorized",
"refundAmount": 0,
"profile": "00001342501",
"DbtrIBAN": null,
"clientId": "998423",
"createdIp": "0.0.0.0",
"authorizationTag": "",
"cartId": 0,
"subtotalItems": "0.00",
"subtotalServices": "0.00",
"subtotalTax": "0.00",
"distributorFee": null,
"paymentHtml": null,
"paymentLanguage": null,
"paymentPostUrl": null,
"paymentPostDataUrl": null,
"paymentAcceptedUrl": null,
"paymentWaitingUrl": null,
"paymentCanceledUrl": null,
"paymentRefusedUrl": null,
"paymentExceptionUrl": null,
"ibanFullname": null,
"ibanId": null,
"ibanBic": null,
"ibanTxEndToEndId": null,
"ibanTxId": null,
"forwardUrl": "",
"authorizationDate": "0000-00-00",
"mandateId": "0",
"creditorName": null,
"creditorAddressLine": null,
"creditorCountry": null,
"creditorIban": null,
"creditorBIC": null,
"virtualIbanId": null,
"virtualIbanReference": null,
"additionalData": "{\"card\":{\"externalProvider\":{\"state\":\"completed\",\"reason\":\"\",\"forwardUrl\":\"\",\"test\":\"true\",\"mid\":\"00001342501\",\"attemptId\":\"1\",\"authorizationCode\":\"no_code\",\"transactionReference\":\"800312407023\",\"dateCreated\":\"2024-07-23T07:30:10+0000\",\"dateUpdated\":\"2024-07-23T07:30:14+0000\",\"dateAuthorized\":\"2024-07-23T07:30:14+0000\",\"status\":\"116\",\"message\":\"Authorized\",\"authorizedAmount\":\"10.00\",\"capturedAmount\":\"0.00\",\"refundedAmount\":\"0.00\",\"creditedAmount\":\"0.00\",\"decimals\":\"2\",\"currency\":\"EUR\",\"ipAddress\":\"0.0.0.0\",\"ipCountry\":\"\",\"deviceId\":\"\",\"cdata1\":\"998423\",\"cdata2\":\"3152544\",\"cdata3\":\"100655503\",\"cdata4\":\"\",\"cdata5\":\"\",\"cdata6\":\"\",\"cdata7\":\"\",\"cdata8\":\"\",\"cdata9\":\"\",\"cdata10\":\"\",\"avsResult\":\"\",\"eci\":\"9\",\"paymentProduct\":\"visa\",\"paymentMethod\":{\"token\":\"f1bed3b91285747c2e5d332a41580e710b726880e4149fb999f271618b8d03c3\",\"cardId\":\"9fd81707-8f41-4a01-b6ed-279954336ada\",\"brand\":\"VISA\",\"pan\":\"411111******1111\",\"cardHolder\":\"M FRAY\",\"cardExpiryMonth\":\"08\",\"cardExpiryYear\":\"2029\",\"issuer\":\"CONOTOXIA SP. Z O.O\",\"country\":\"PL\"},\"threeDSecure\":\"\",\"fraudScreening\":{\"scoring\":\"0\",\"result\":\"NOT_LAUNCHED\",\"review\":\"\"},\"order\":{\"id\":\"order_1234567890\",\"dateCreated\":\"2024-07-23T07:30:10+0000\",\"attempts\":\"1\",\"amount\":\"10.00\",\"shipping\":\"0.00\",\"tax\":\"0.00\",\"decimals\":\"2\",\"currency\":\"EUR\",\"customerId\":\"\",\"language\":\"en_US\",\"email\":\"\"},\"debitAgreement\":{\"id\":\"11209240\",\"status\":\"available\"}}}}"
}
]
}Capture the funds
To capture funds following an authorization, use the following request.
bash
curl -X POST {baseUrl}/v1/topups/cards/authorizations/{authorizationId}/payins \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
-d '{payload}'Here is an example of {payload}:
json
{
"amount":10,
"currency":"EUR"
}Returns the Payin and sends payin.create and payin.update webhooks.
json
{
"payins": [
{
"payinId": "89f82b27-be27-527c-9b93-eab65fb7a0e4",
"userId": "100655503",
"walletId": "3152544",
"userFirstname": "John",
"walletEventName": "Event_test",
"walletAlias": "event-test-669f5b8e1e9cf",
"userLastname": "Smith",
"messageToUser": "The financial institution has processed the payment.",
"payinStatus": "VALIDATED",
"paymentMethodId": "25",
"amount": 10,
"currency": "EUR",
"createdDate": "",
"codeStatus": "150118",
"informationStatus": "Captured",
"refundAmount": 0,
"profile": "00001342501",
"DbtrIBAN": null,
"createdIp": "0.0.0.0",
"payinTag": "",
"cartId": 0,
"subtotalItems": "0.00",
"subtotalServices": "0.00",
"subtotalTax": "0.00",
"distributorFee": null,
"paymentHtml": null,
"paymentLanguage": null,
"paymentPostUrl": null,
"paymentPostDataUrl": null,
"paymentAcceptedUrl": null,
"paymentWaitingUrl": null,
"paymentCanceledUrl": null,
"paymentRefusedUrl": null,
"paymentExceptionUrl": null,
"ibanFullname": null,
"ibanId": null,
"ibanBic": null,
"ibanTxEndToEndId": null,
"ibanTxId": null,
"forwardUrl": null,
"payinDate": "0000-00-00",
"mandateId": "0",
"creditorName": null,
"creditorAddressLine": null,
"creditorCountry": null,
"creditorIban": null,
"creditorBIC": null,
"virtualIbanId": null,
"virtualIbanReference": null,
"additionalData": "{\"card\":{\"externalProvider\":{\"operation\":\"capture\",\"test\":\"true\",\"mid\":\"00001342501\",\"authorizationCode\":\"no_code\",\"transactionReference\":\"800312407520\",\"dateCreated\":\"2024-07-23T08:59:40+0000\",\"dateUpdated\":\"2024-07-23T09:06:49+0000\",\"dateAuthorized\":\"2024-07-23T08:59:44+0000\",\"status\":\"118\",\"message\":\"Captured\",\"authorizedAmount\":\"10.00\",\"capturedAmount\":\"10.00\",\"refundedAmount\":\"0.00\",\"decimals\":\"2\",\"currency\":\"EUR\"}}}"
}
]
}
Note – You can create several captures for an authorization if both:
- The total amount doesn't exceed the initial authorization amount.
- The capture occurs within 7 days of the authorization.