Skip to main content

Authorize and Capture Flow

In a regular payment flow, when you create a payment, your customer authorizes the payment with the payment method and Dibsy automatically collects the funds for you.

With the authorize and capture flow, you can break this process up into two separate steps. First, you gather the customer's authorization to place a hold for a specified amount on their account. Then at a later point you can decide whether you want Dibsy to collect (capture) the "authorized" funds fully, or to cancel (void) the authorization.

Placing a hold is recommended in cases where you are not yet sure up front if and when you will be able to fulfil the order completely. It reduces the risk of chargebacks and operational efforts of handling refunds in case you cannot fulfil the order.

warning

An "authorized" payment is not a "succeeded" payment. Unless the payment is captured and status is "succeeded", the funds will not be settled to your bank account.

To capture the authorized payment, you must call the Capture Payment API. If you wish to immediately reverse the authorization, you must call the Cancel Payment API.

Create a Authorization Payment

Compared to the regular payment flow, you must define the autoCapture field as false.

Request

curl --location --request POST 'https://api.dibsy.one/v2/payments' \
--header 'Authorization: Bearer sk_test_mpmEeSyDEnRkabhjbgswr' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount": {
        "value": "5.00",
        "currency": "QAR"
    },
    "description": "Order ##1236",
    "method": "creditcard",
    "autoCapture": false,
    "cardToken": "tk_akfngi43bhf",
    "redirectUrl": "https://example.com/order/12345",
    "webhookUrl": "https://example.com/webhook/12345",
    "metadata": {
        "order_id": "1236"
    }
}'

Response

HTTP/1.1 201 Created
Content-Type: application/hal+json

{
    "id": "pt_3S2V6lFTSE6OSUIr7u",
    "resource": "payment",
    "mode": "live",
    "amount": {
        "value": "5.00",
        "currency": "QAR"
    },
    "description": "Order ##1236",
    "method": "creditcard",
    "redirectUrl": "https://example.com/order/12345",
    "webhookUrl": "https://example.com/webhook/12345",
    "status": "authorized",
    "organizationId": "300000",
    "sequenceType": "oneoff",
    "metadata": {
        "order_id": "1236"
    },
    "createdAt": "2021-12-26T21:09:32.225554757",
    "expiresAt": "2021-12-26T21:24:32.148",
    "authorizedAt": "2021-12-26T21:09:32.225554757",
    "_links": {
        "self": {
            "href": "http://api.dibsy.one/v2/payments/pt_oN4NPMdAj2w7W7ZlQY",
            "type": "application/hal+json"
        },
        "dashboard": {
            "href": "https://dashboard.dibsy.one/payments/pt_oN4NPMdAj2w7W7ZlQY",
            "type": "text/html"
        },
        "documentation": {
            "href": "https://api.dibsy.dev/##operation/Create%20Payment",
            "type": "text/html"
        }
    }
}

Capture the payment

To collect the funds that the customer authorized, you can create a capture on the payment using the Create Capture endpoint. 

curl --location 'https://api.dibsy.one/v2/payments/pt_3S2V6lFTSE6OSUIr7u/captures' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer sk_test_mpmEeSyDEnRkabhjbgswr'

Release an authorization

To release an authorization call the Cancel Payment endpoint on a payment that has a status of authorized.

Request

curl --location --request DELETE 'https://api.dibsy.one/v2/payments/pt_3S2V6lFTSE6OSUIr7u' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer sk_test_mpmEeSyDEnRkabhjbgswr'

Response

HTTP/1.1 200 OK
Content-Type: application/hal+json
{
    "id": "pt_3S2V6lFTSE6OSUIr7u",
    "resource": "payment",
    "mode": "live",
    "amount": {
        "value": "5.00",
        "currency": "QAR"
    },
    "amountNet": {
        "value": "3.85",
        "currency": "QAR"
    },
    "amountRemaining": {
        "value": "5.00",
        "currency": "QAR"
    },
    "description": "Order ##1236",
    "method": "creditcard",
    "redirectUrl": "https://example.com/order/12345",
    "webhookUrl": "https://example.com/webhook/12345",
    "status": "canceled",
    "organizationId": "300000",
    "sequenceType": "oneoff",
    "metadata": {
        "order_id": "12345"
    },
    "details": {
        "cardCountryCode": "GB",
        "cardHolder": "Kenny Mcormick",
        "cardLabel": "Visa",
        "cardNumber": "4242 42XX XXXX 4242"
    },
    "createdAt": "2022-01-03T09:10:33.663",
    "expiresAt": "2022-01-03T09:25:33.585",
    "cancelledAt": "2022-01-03T09:11:01.94",
    "_links": {
        "self": {
            "href": "http://api.dibsy.one/v2/payments/pt_NfszStROpb8poeUrIl",
            "type": "application/hal+json"
        },
        "dashboard": {
            "href": "https://dashboard.dibsy.one/payments/pt_NfszStROpb8poeUrIl",
            "type": "text/html"
        },
        "documentation": {
            "href": "https://api.dibsy.dev/##operation/Get%20Payment",
            "type": "text/html"
        }
    }
}