Skip to content

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:

  1. Authorize an amount to capture up to 7 days later.
  2. 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.

Paperclip icon

Prerequisites – Steps to do before the authorization:

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 icon

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.