On-demand payments
On-demand payments allow you to charge your customers, without them filling the checkout form or completing authentication. All on-demand payments happen server-to-server and without the direct participation of the customer.
info
To use this feature, please contact Dibsy Customer Success Team.
tip
To reduce your risk of chargebacks, it is very important that you only use on-demand payments when your customer gives you clear consent and are notified before and after being charged.
Accept on-demand payments
Step 1 - Create a customer
All on-demand payments must have a customer parameter. If you don’t have a customer, you must create a unique customer using the Customers API, and save the customer’s id in your database.
Request
curl --location --request POST 'https://api.dibsy.one/v2/customers' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer sk_test_mpmEeSyDEnRkXW6qakbhebjadg' \
--data-raw '{
"name": "Randy Marsh",
"email": "randy.m@hotmail.com",
"phone": "+97433999911",
"customFields": {
"homeAddress": "South Park",
"country": "QA"
}
}'
Response
HTTP/1.1 201 Created
Content-Type: application/hal+json
{
"id": "ct_jNjHWvlEiFdyKIfYLl",
"resource": "customer",
"name": "Randy Marsh",
"email": "randy.m@gmail.com",
"phone": "+97433999911",
"organizationId": "300000",
"customFields": {
"country": "QA",
"homeAddress": "South Park"
},
"_links": {
"self": {
"href": "http://api.dibsy.one/v2/customers/ct_jNjHWvlEiFdyKIfYLl",
"type": "application/hal+json"
},
"dashboard": {
"href": "https://dashboard.dibsy.one/customers/ct_jNjHWvlEiFdyKIfYLl",
"type": "text/html"
},
"documentation": {
"href": "https://api.dibsy.dev//#operation/Create%20Customer",
"type": "text/html"
}
}
}
Step 2 - Complete the first payment
Create a payment with the customerId parameter to your customer’s id, the sequenceType parameter to "recurring" and the cardToken. If the cardToken is being used for the first time, your customer must first complete the 3-D secure authentication and therefore the created payment status is open.
Once the first payment has been completed successfully, the payment status becomes succeeded and you must save the cardToken in your database for future use.
First-time payments
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 #531236",
"method": "creditcard",
"sequenceType": "recurring",
"cardToken": "tk_akfngi43bhf",
"customerId": "ct_jNjHWvlEiFdyKIfYLl",
"redirectUrl": "https://example.com/order/531236",
"webhookUrl": "https://example.com/webhook/531236",
"metadata": {
"order_id": "531236"
}
}'
Response
HTTP/1.1 201 Created
Content-Type: application/hal+json
{
"id": "pt_D8ufYrfix2vYUPK2ue",
"resource": "payment",
"mode": "test",
"amount": {
"value": "5.00",
"currency": "QAR"
},
"description": "Order #531236",
"method": "creditcard",
"redirectUrl": "https://example.org/order/531236",
"webhookUrl": "https://example.org/webhook/531236",
"status": "open",
"organizationId": "300000",
"sequenceType": "recurring",
"metadata": {
"order_id": "531236"
},
"createdAt": "2021-12-26T21:10:33.638291726",
"expiresAt": "2021-12-26T21:25:33.561",
"customerId": "ct_jNjHWvlEiFdyKIfYLl",
"_links": {
"self": {
"href": "http://api.dibsy.one/v2/payments/pt_D8ufYrfix2vYUPK2ue",
"type": "application/hal+json"
},
"checkout": {
"href": "https://redirect.dibsy.one/creditcard/red_SIxkmZDxdMQKRex3aU",
"type": "text/html"
},
"dashboard": {
"href": "https://dashboard.dibsy.one/payments/pt_D8ufYrfix2vYUPK2ue",
"type": "text/html"
},
"documentation": {
"href": "https://api.dibsy.dev/#operation/Create%20Payment",
"type": "text/html"
}
}
}
Step 3 - Using your saved card token
Now that your first payment is successful, your cardToken becomes valid and can be used to make payments on-demand. With this cardToken, you can process payments server-to-server without the need of your customer reentering their card details.
Simply create a payment with parameters cardToken and customerId you saved in the last session and sequenceType to recurring. This will result in one of two response types.
Direct Capture
If the payment passes through our risk filters, the cardToken will be charged without any interaction from the customer. The API will respond with status succeeded or failed.
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": "20.00",
"currency": "QAR"
},
"description": "Order #2381236",
"method": "creditcard",
"cardToken": "tk_akfngi43bhf",
"sequenceType": "recurring",
"customerId": "ct_jNjHWvlEiFdyKIfYLl",
"redirectUrl": "https://example.com/order/2381236",
"webhookUrl": "https://example.com/webhook/2381236",
"metadata": {
"order_id": "2381236"
}
}'
Response
HTTP/1.1 201 Created
Content-Type: application/hal+json
{
"id": "pt_dijsn0uuZMAclEuIGd",
"resource": "payment",
"mode": "test",
"amount": {
"value": "20.00",
"currency": "QAR"
},
"amountNet": {
"value": "18.42",
"currency": "QAR"
},
"amountRemaining": {
"value": "20.00",
"currency": "QAR"
},
"description": "Order #2381236",
"method": "creditcard",
"redirectUrl": "https://example.com/order/2381236",
"webhookUrl": "https://example.com/webhook/2381236",
"status": "succeeded",
"organizationId": "300000",
"sequenceType": "recurring",
"metadata": {
"order_id": "2381236"
},
"details": {
"cardCountryCode": "GB",
"cardHolder": "23",
"cardLabel": "Visa",
"cardNumber": "4242 42XX XXXX 4242"
},
"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"
}
}
}
Requires Interaction
If the payment does not pass through our risk filters, we will require additional authentication from the customer to ensure that the payment is not fraudulent. The API will respond with status open and the customer must be redirected to the 3-D Secure Authentication page to complete the payment. The flow is similar to the first time customer saves their card.
Response
HTTP/1.1 201 Created
Content-Type: application/hal+json
{
"id": "pt_kahBASBJjsjBSBOND",
"resource": "payment",
"mode": "test",
"amount": {
"value": "5.00",
"currency": "QAR"
},
"description": "Order #531237",
"method": "creditcard",
"redirectUrl": "https://example.org/order/531236",
"webhookUrl": "https://example.org/webhook/531236",
"status": "open",
"organizationId": "300000",
"sequenceType": "recurring",
"metadata": {
"order_id": "531237"
},
"createdAt": "2021-12-26T21:10:33.638291726",
"expiresAt": "2021-12-26T21:25:33.561",
"customerId": "ct_jNjHWvlEiFdyKIfYLl",
"_links": {
"self": {
"href": "http://api.dibsy.one/v2/payments/pt_kahBASBJjsjBSBOND",
"type": "application/hal+json"
},
"checkout": {
"href": "https://redirect.dibsy.one/creditcard/red_kahBASBJjsjBSBOND",
"type": "text/html"
},
"dashboard": {
"href": "https://dashboard.dibsy.one/payments/pt_kahBASBJjsjBSBOND",
"type": "text/html"
},
"documentation": {
"href": "https://api.dibsy.dev/#operation/Create%20Payment",
"type": "text/html"
}
}
}