Skip to main content

Integration Guidelines

This guide outlines the steps required to offer installment payment plans to your customers using their credit cards. It covers two main flows:

  • Get Available Plans: Retrieve eligible installment plans based on the customer's card details and transaction amount.

  • Create Payment with Plan: Finalize the transaction by selecting a plan and processing the payment.

Get Plans

The Get Plans API requires two inputs, the card token and amount to be charged to the customer. Based on several factors like card type, credit history, etc, the API will respond with possible installment plans.

It is also possible that the issuing bank does not offer any installment plans under the card to the customer. In this case, you can proceed to use the token to charge the card directly.

Important: Installments are available for purchases of QAR 500.00 and more.

Request

POST /v2/bnpl/vis/plans

{
  "amount": {
    "value": "1000.00",
    "currency": "QAR"
  },
  "cardToken": "tk_akfngi43bhf"
}

Response

{
    "count": 4,
    "plans": [
        {
            "resource": "plan",
            "planId": "pln_123",
            "mode": "live",
            "duration": "3",
            "frequency": "month",
            "installment": {
                "value": "336.62",
                "currency": "QAR"
            },
            "rate": "0.33",
            "processingFee": {
                "value": "0.00",
                "currency": "QAR"
            },
            "tnc": {
                "en": {
                    "text": "Terms and conditions for 3-month payment plan",
                    "url": "https://abcbank.com/en/installments/tnc"
                },
                "ar": {
                    "text": "الشروط والأحكام لخطة الدفع لمدة 3 أشهر",
                    "url": "https://abcbank.com/ar/installments/tnc"
                }
            }
        },
        { /* 6-month payment plan */},
        { /* 9-month payment plan */},
        { /* 12-month payment plan */}
    ]
}

Create Payment with Plan ID

Once the customer selects a suitable installment plan, you can initiate the payment using the corresponding "planId".

Request

/v2/payments

{
    "amount": {
        "value": "1000.00",
        "currency": "QAR"
    },
    "description": "Order #2381236",
    "method": "creditcard",
    "cardToken": "tk_akfngi43bhf",
    "sequenceType": "recurring",
    "planId": "pln_123",
    "customerId": "ct_jNjHWvlEiFdyKIfYLl",
    "redirectUrl": "https://webstore.com/order/2381236",
    "webhookUrl": "https://webstore.com/webhook/2381236",
    "metadata": {
        "order_id": "2381236"
    }
}

Response

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

{
    "id": "pt_dijsn0uuZMAclEuIGd",
    "resource": "payment",
    "mode": "live",
    "amount": {
        "value": "1000.00",
        "currency": "QAR"
    },
    "amountNet": {
        "value": "990.00",
        "currency": "QAR"
    },
    "amountRemaining": {
        "value": "1000.00",
        "currency": "QAR"
    },
    "description": "Order #2381236",
    "method": "creditcard",
    "redirectUrl": "https://webstore.com/order/2381236",
    "webhookUrl": "https://webstore.com/webhook/2381236",
    "status": "succeeded",
    "organizationId": "300000",
    "sequenceType": "recurring",
    "metadata": {
        "order_id": "2381236"
    },
    "details": {
        "cardCountryCode": "GB",
        "cardHolder": "Kenny McCormick",
        "cardLabel": "Visa",
        "cardNumber": "4242 42XX XXXX 4242",
        "bnpl": "vis"
    },
    "createdAt": "2021-12-26T21:13:21.523495913",
    "expiresAt": "2021-12-26T21:28:21.446",
    "customerId": "ct_jNjHWvlEiFdyKIfYLl",
    "paidAt": "2021-12-26T21:13:24.611405222",
    "_links": {
        "self": {
            "href": "http://api.dibsy.one/v2/payments/pt_dijsn0uuZMAclEuIGd",
            "type": "application/hal+json"
        },
        "dashboard": {
            "href": "https://dashboard.dibsy.one/payments/pt_dijsn0uuZMAclEuIGd",
            "type": "text/html"
        },
        "documentation": {
            "href": "https://api.dibsy.dev/#operation/Create%20Payment",
            "type": "text/html"
        }
    }
}