Provide crypto payer identification
When you accept crypto payments, send any payer identification you already hold from your backend. Hubpay stores these details against the payer and reuses them for later payment requests.
Hubpay checkout asks the payer for identification only when all of the following are true:
- The payer selects crypto.
- The saved payer record does not contain the required identification.
- The information is required for the crypto payment.
Supplying the information yourself keeps the checkout shorter. The checkout form is a fallback for missing information, not the preferred way to collect information that your system already holds.
Information to supply
| Payer type | Identification fields |
|---|---|
INDIVIDUAL | identificationDocumentType and identificationDocumentNumber |
BUSINESS | registrationNumber |
For an individual, identificationDocumentType supports:
NATIONAL_IDPASSPORTDRIVING_LICENSE
The individual document type and number must be supplied together. Do not send individual document fields for a business payer.
These identification fields are optional at the general API boundary because they are type-specific and are not needed for non-crypto payments. When creating a crypto-enabled payer, also provide the other fields marked as required for crypto in the Payer API schema.
Address fields for crypto payments
Provide the individual's residential address or the company's business address.
| Field | Individual | Business |
|---|---|---|
country | Required, as a two-letter country code | Required, as a two-letter country code |
address | Required | Required |
areaOrCity | Required | Optional |
provinceOrState | Optional | Required; use the emirate for a UAE business |
postalCode | Optional | Optional for the UAE (AE); required for other countries |
phoneNumber | Required | Required |
For a UAE address, leave postalCode blank or omit it. Do not send N/A, 0000 or a made-up postcode. Include the street, building and unit details in address, where applicable.
Create a payment request with an identified payer
You can provide a new payer inline in the payment request. Set cryptoEnabled to true and put the identification fields inside payer, not at the top level of the payment request.
| Payment request field | What to supply |
|---|---|
payer.type | INDIVIDUAL or BUSINESS |
payer.identificationDocumentType | The document type for an individual payer |
payer.identificationDocumentNumber | The document number for an individual payer |
payer.registrationNumber | The registration number for a business payer |
payer.cryptoEnabled | true |
Complete the remaining payment request and payer fields as described in the Create payment request schema.
The same nested payer structure works with executionMode set to PAYMENT_LINK.
Use an existing payer
If you already have a Hubpay payer ID:
- Supply the identification when you create the payer, or add it using Update payer.
- Create the payment request with
payerIdinstead of an inlinepayer.
Do not send both payerId and payer in the same payment request.
Checkout fallback
When the saved payer identification is complete, checkout continues without displaying an identification form.
If the information is missing, checkout pauses the crypto flow and asks the payer for:
- Document type and number for an individual payer
- Corporate registration number for a business payer
After the payer submits the information, Hubpay saves it against the payer and resumes the selected crypto journey.
