# BNPL integration for Markets

One of the use cases of serviceX is BNPL Gateway.

This page is for Markets to integrate the BNPL Gateway.

If you have not set up a Market yet, please refer to Integration guide.

# Flow

create order

After users have finished the BNPL transaction, you will receive a webhook event regarding the order status. You will just need to process the order status on your system.

Once you have finished setting up a Market, what you need to do is

  1. Create an order for BNPL
  2. Handle webhook events

# Create an order

Every BNPL transaction should be associated with an order. You need to generate a new order object on your backend. You will obtain order ID, so you can check the order status afterwards.


Please ensure you keep Order ID in your system because it is necessary when the transaction is completed.

# Sandbox
[POST] https://sandbox-api.credify.dev/v1/bnpl-consumers/orders

# Production
[POST] https://api.credify.one/v1/bnpl-consumers/orders
Request header:
- "Authorization": YOUR_TEMPORARY_TOKEN

This is a sample JSON object that is to be sent in a request body.

  "reference_id": "string",
  "total_amount": {
    "value": "120000",
    "currency": "VND"
  "order_lines": [
      "name": "Soda",
      "reference_id": "string",
      "image_url": "string",
      "product_url": "string",
      "quantity": 12,
      "unit_price": {
        "value": "10000",
        "currency": "VND"
      "subtotal": {
        "value": "120000",
        "currency": "VND"
      "measument_unit": "EACH"
  "payment_recipient": {
    "name": "string",
    "number": "string",
    "branch": "string",
    "bank": "string"
  • reference_id: string
    • ID that you want to use in your platform to look up the order
  • total_amount: object
    • value is a string value that represents price.
    • currency is VND / USD / JPY (currently, only VND is available)
  • order_lines: array<object>
    • name is item's name
    • reference_id is ID that you use in your platform to represent the item (optional)
    • image_url is image URL to the item (optional)
    • product_url is detail URL to the item (optional)
    • quantity is the number of items
    • unit_price is how much the item costs per unit (e.g. 1 item, 1 kg)
    • subtotal is how much the item costs
    • measurement_unit is how to measure the item
  • payment_recipient: object
    • name is a recipient's name
    • number is a recipient's bank account number
    • branch is a recipient's bank branch
    • bank is a recipient's bank name

# Implementation with SDK

  • Node.js
  • Java
  • .NET
const { Credify } = require("@credify/nodejs");

// You obtain these on the serviceX dashboard.
const signingPrivateKey = `-----BEGIN PRIVATE KEY-----
your private key...
-----END PRIVATE KEY-----`;
const apiKey = "YOUR_API_KEY";

const referenceId = req.body.reference_id;
const totalAmount = req.body.total_amount;
const orderLines = req.body.order_lines;
const paymentRecipient = req.body.payment_recipient;
// This is a sample. It should use `async`
const credify = await Credify.create(signingPrivateKey, apiKey, { mode: "sandbox" });
// This is a sample. It should use `async`
const data = await credify.bnpl.createOrder(

# Handle webhook events

Once BNPL transaction is completed, you will receive a webhook event from Credify, so you can update the purchase status to completed. This webhook event has Authorization header to prove it is coming from the Credify server. You can verify the access token with Token Introspection API or SDK.

This webhook event contains BNPL order ID that you are supposed to keep in your cache or storage.

Last Updated: 5/5/2022, 5:29:54 AM