Ctrlk
HOMEAPI ReferencePayment Demo

Tokenization

I. Tokenization Configuration

Contact your account manager to apply for activation of Tokenization products, and confirm whether the subsequent payment for MIT-type transactions can be activated for you.

Our Tokenization solution enables merchants to securely reuse previously authorized payment credentials for future transactions without handling sensitive card data directly.

During the tokenization process, a payment method is associated with a unique customerId and paymentMethod ID. These identifiers can be used to reference the underlying payment credentials in subsequent transactions.

Unlike traditional tokenization solutions, our platform does not return a standalone payment token. Instead, merchants should store the returned customerId and paymentMethod ID and use them for future payment requests.

The underlying payment credentials are securely managed by the relevant financial institutions, payment networks, or token service providers. Our platform maintains the relationship between the customer, payment method, and the corresponding payment credentials, allowing merchants to initiate future transactions without storing or transmitting sensitive card data.

This approach simplifies integration, reduces merchants' exposure to sensitive payment information, and supports a variety of future payment scenarios, including Cardholder-Initiated Transactions (CIT), Merchant-Initiated Transactions (MIT), recurring payments, and other tokenized payment use cases.

Note: No payment token is returned during tokenization. Merchants must persist the customerId and paymentMethod ID returned by the API and use them for all subsequent payments involving the stored payment credentials.

II. Token creation

1

Create customer

The merchant server calls the create customer interface: /customers/create to obtain the customer ID, for example cus_1938157433067143170.

Note: This customer ID should be bound to the merchant website user's unique ID.

Request example:

{
  "address": {
    "city": "Asheville",
    "country": "US",
    "line1": "3968 Fidler Drive",
    "line2": "",
    "postalCode": "28806",
    "state": "North Carolina"
  },
  "description": "",
  "email": "[email protected]",
  "firstName": "Mark",
  "lastName": "Merrill",
  "phone": "2106276464"
}

Response example :

{
  "code": "success",
  "msg": "success",
  "data": {
    "id": "cus_1938157433067143170",
    "email": "[email protected]",
    "firstName": "Mark",
    "lastName": "Merrill",
    "phone": "2106276464",
    "description": "",
    "address": {
      "city": "Asheville",
      "country": "US",
      "line1": "3968 Fidler Drive",
      "line2": "",
      "postalCode": "28806",
      "state": "North Carolina"
    },
    "shipping": null,
    "created": "2025-06-26T08:48:35.925Z"
  }
}
2

Create paymentMethod

The merchant server calls the payment method creation interface: /payment_methods/create to obtain the payment method ID, for example

pm_1938159585009336322

Request example:

{
  "billingDetails": {
    "address": {
      "city": "Asheville",
      "country": "US",
      "line1": "3968 Fidler Drive",
      "line2": "",
      "postalCode": "28806",
      "state": "North Carolina"
    },
    "email": "[email protected]",
    "firstName": "Mark",
    "lastName": "Merrill",
    "phone": "2106276464",
    "description": ""
  },
  "card": {
    "cardNo": "4242424242424242",
    "expMonth": "04",
    "expYear": "2028",
    "securityCode": "123"
  },
  "type": "card",
  "merchantPaySite": "https://test.com/"
}

Response example：

{
  "code": "success",
  "msg": "success",
  "data": {
    "id": "pm_1938159585009336322",
    "type": "card",
    "billingDetails": {
      "firstName": "Mark",
      "lastName": "Merrill",
      "phone": "2106276464",
      "email": "[email protected]",
      "address": {
        "city": "Asheville",
        "country": "US",
        "line1": "3968 Fidler Drive",
        "line2": "",
        "postalCode": "28806",
        "state": "North Carolina"
      }
    },
    "created": "2025-06-26T08:57:08.987Z",
    "customerId": null,
    "card": {
      "brand": "Visa",
      "country": "GB",
      "expMonth": "04",
      "expYear": "2028",
      "fingerprint": "KB2kvSZ3i2un0lmfwIc873kvRJJem4AAEvA/fo3HPPo=",
      "last4": "4242",
      "tokenType": null
    },
    "boleto": null,
    "pix": null,
    "creditCardBrazil": null
  }
}
3

Create Payment

The merchant server calls the payment creation interface (support zero amount authorization): /payment/create. When calling the current interface, pass in customerId and paymentMethod at the same time, and set setupFutureUsage to on. Moneycollect will bind customerId and paymentMethod for subsequent tokenization transactions.

Request example：

{
  "amount":"1000",
  "confirmationMethod": "automatic",
  "currency": "USD",
  "customerId": "cus_1938157433067143170",
  "description": "test tokenization",
  "ip": "192.168.3.1",
  "confirm": "true",
  "lineItems": [
    {
      "amount": 10,
      "currency": "USD",
      "description": "test tokenization",
      "images": ["https://payment.moneycollect.com/static/img/checkout_platforms.e4491f3.png"],
      "name": "test",
      "quantity": 1
    }
  ],
  "notifyUrl": "https://www.moneycollect.com/services/v1/callResult",
  "orderNo": "47598388037375697",
  "paymentMethod":"pm_1938159585009336322",
  "preAuth": "n",
  "receiptEmail": "[email protected]",
  "returnUrl": "https://www.moneycollect.com/services/v1/redirectResultTest?bankCode=TestBankCode",
  "setupFutureUsage": "on",
  "statementDescriptor": "TEST",
  "statementDescriptorSuffix": "",
  "website": "https://test.com/"
}

Response example：

{
  "code": "success",
  "msg": "success",
  "data": {
    "id": "pt_1938161587181322242",
    "amount": "1000",
    "currency": "USD",
    "confirmationMethod": "automatic",
    "customerId": "cus_1938157433067143170",
    "description": "test tokenization",
    "paymentMethod": "pm_1938159585009336322",
    "paymentMethodTypes": [
      "card"
    ],
    "paymentMethodType": "card",
    "receiptEmail": "[email protected]",
    "setupFutureUsage": "on",
    "orderNo": "47598388037375697",
    "notifyUrl": "https://www.moneycollect.com/services/v1/callResult",
    "returnUrl": "https://moneycollect.com/services/v1/redirectResultTest?bankCode=TestBankCode",
    "website": "https://test.com/",
    "ip": "192.168.3.1",
    "preAuth": "n",
    "statementDescriptor": "TEST",
    "clientSecret": "pt_1938161587181322242_secret_564C4368F6A6523E5E8099C88E549FB7",
    "canceledAt": null,
    "cancellationReason": null,
    "amountReceived": "0",
    "amountCapturable": "0",
    "created": "2025-06-26T09:05:06.346Z",
    "riskInfo": {
      "riskScore": 0,
      "riskMessage": "risk_pass"
    },
    "status": "succeeded",
    "displayStatus": "succeeded",
    "errorCode": null,
    "errorMessage": null,
    "invoiceId": null,
    "fromChannel": null,
    "use3D": false
  }
}

III. CIT scenarios

Use tokens for payments in future cardholder-initiated transaction

The merchant server calls the payment creation endpoint (/payment/create) using the previously saved customerId and paymentMethod. For subsequent cardholder-initiated transactions (CIT), set setupFutureUsage to on and specify "subsequentInitialType": "cit" to process future payments using the stored payment method.

Note: Subsequent cit transactions may trigger the 3D transaction process.

Request example：

Response example：

IV. MIT scenarios

Use tokens for payments in future merchant-initiated transaction

The merchant server calls the payment creation endpoint (/payment/create) using the previously saved customerId and paymentMethod. For subsequent merchant-initiated transactions (MIT), set setupFutureUsage to on and specify "subsequentInitialType": "mit" to process future payments using the stored payment method.

Request example：

Response example：

PreviousAndroidNextSubscriptions

Last updated