Initiate a collection

Create a card collection request for a business wallet. Card collections require a verified customer and card details, and may not be enabled for every business. Customer attachment after creation is not supported for API card collections. Required scope: collection:create.

POSTapi-prod.blaaiz.com/api/external/collection

Authorization

oauth2ClientCredentials collection:create

AuthorizationBearer <token>

Use your OAuth client credentials to obtain a short-lived Bearer token from POST /oauth/token.

In: header

Scope: collection:create

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

method*"card"

Collection method. Use card.

Value in

"card"

amount*number

Amount to collect. Minimum value is 0.1.

wallet_id*string

ID of the business wallet to credit.

customer_id?string

Business customer ID. Required for card collections. The customer must belong to the business and be VERIFIED.

phone?string

Optional customer phone number.

card_holder_name?string

Full card holder name. Required for card collections.

card_number?string

16-digit card number. Required for card collections.

expiry?string

Card expiry in MM/YY format. Required for card collections.

cvc?string

3-digit card CVC. Required for card collections.

redirect_url?string

Optional HTTPS URL to redirect the customer to after payment authorization (e.g. 3DS). Blaaiz appends transaction_id and status query parameters to this URL before redirecting. Maximum 2048 characters.

Formaturi

Lengthlength <= 2048

merchant_reference?string

Your own reference for this collection. Blaaiz stores the value and returns it on the transaction endpoints and the webhooks. Each value must be unique for your business. Maximum 255 characters.

Lengthlength <= 255

Response Body

`application/json`

Initiate a collection

curl --request POST \  --url 'https://example.com/api/external/collection' \  --header 'Content-Type: application/json' \  --data '{  "method": "card",  "amount": 50000,  "wallet_id": "wallet_123",  "customer_id": "customer_123",  "card_holder_name": "John Doe",  "card_number": "4242424242424242",  "expiry": "12/30",  "cvc": "123",  "phone": "+2348012345678",  "redirect_url": "https://merchant.example.com/payment/callback"}'

{  "message": "Collection initiated successfully.",  "transaction_id": "txn_987654322",  "url": "https://checkout.example.com/card-auth/xyz789"}