Sell prepaid credit

curl --request POST \
  --url https://bouclay.com/api/v1/customers/{customer}/credit-purchases \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "priceId": "price_123",
  "amount": 10000,
  "currency": "NGN",
  "creditAmount": 123,
  "revenueCode": "<string>",
  "expiresAfterMonths": 60,
  "collectionMode": "manual",
  "paymentMethod": "<string>",
  "customData": {}
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    priceId: 'price_123',
    amount: 10000,
    currency: 'NGN',
    creditAmount: 123,
    revenueCode: '<string>',
    expiresAfterMonths: 60,
    collectionMode: 'manual',
    paymentMethod: '<string>',
    customData: {}
  })
};

fetch('https://bouclay.com/api/v1/customers/{customer}/credit-purchases', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://bouclay.com/api/v1/customers/{customer}/credit-purchases"

payload = {
    "priceId": "price_123",
    "amount": 10000,
    "currency": "NGN",
    "creditAmount": 123,
    "revenueCode": "<string>",
    "expiresAfterMonths": 60,
    "collectionMode": "manual",
    "paymentMethod": "<string>",
    "customData": {}
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://bouclay.com/api/v1/customers/{customer}/credit-purchases",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'priceId' => 'price_123',
    'amount' => 10000,
    'currency' => 'NGN',
    'creditAmount' => 123,
    'revenueCode' => '<string>',
    'expiresAfterMonths' => 60,
    'collectionMode' => 'manual',
    'paymentMethod' => '<string>',
    'customData' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "data": {
    "object": "credit_purchase",
    "invoice": {
      "id": "<string>",
      "number": "<string>",
      "status": "<string>",
      "billingReason": "<string>",
      "purpose": "card_verification",
      "collectionMode": "automatic",
      "currency": "<string>",
      "subtotal": 1,
      "grantApplied": 1,
      "taxTotal": 1,
      "taxes": [
        {
          "name": "VAT",
          "rate": 7.5,
          "reason": "<string>",
          "inclusive": true,
          "amount": 1
        }
      ],
      "total": 1,
      "minimumCommitment": {
        "amount": 123,
        "counted": 123,
        "shortfall": 123
      },
      "spendingCap": {
        "amount": 123,
        "counted": 123,
        "takenBack": 123
      },
      "sellerTaxId": "<string>",
      "sellerVatRegistered": true,
      "billingAddress": {},
      "reference": "<string>",
      "amountPaid": 1,
      "amountCredited": 1,
      "balanceApplied": 0,
      "amountDue": 1,
      "paidAt": "2023-11-07T05:31:56Z",
      "customer": {
        "id": "<string>",
        "email": "jsmith@example.com",
        "name": "<string>",
        "taxId": "<string>"
      },
      "subscription": {
        "id": "<string>",
        "status": "<string>",
        "pauseReason": "requested"
      },
      "payment": {
        "id": "<string>",
        "status": "pending",
        "amount": 1,
        "amountRefunded": 1,
        "amountChargedBack": 1,
        "currency": "<string>",
        "failureCode": "<string>",
        "failureReason": "<string>",
        "attemptNumber": 123,
        "manualMethod": "cash",
        "reference": "<string>",
        "processedAt": "2023-11-07T05:31:56Z",
        "invoice": {
          "id": "<string>"
        },
        "customer": {
          "id": "<string>"
        },
        "createdAt": "2023-11-07T05:31:56Z"
      },
      "dueAt": "2023-11-07T05:31:56Z",
      "hostedUrl": "<string>",
      "invoicePdfUrl": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "lines": [
        {
          "id": 123,
          "description": "<string>",
          "kind": "plan",
          "quantity": 123,
          "unitAmount": 1,
          "quantityLabel": "<string>",
          "tierBreakdown": "<string>",
          "total": 1,
          "billingTiming": "advance",
          "periodStart": "2023-11-07T05:31:56Z",
          "periodEnd": "2023-11-07T05:31:56Z",
          "usageQuantity": 123,
          "taxCategory": "standard",
          "revenueCode": "<string>",
          "discountAmount": 1,
          "grantApplied": 1,
          "taxAmount": 1,
          "taxRate": 7.5,
          "taxName": "VAT",
          "taxReason": "export of services",
          "taxInclusive": true
        }
      ]
    },
    "grants": [
      {
        "id": "cg_123",
        "object": "credit_grant",
        "customer": {
          "id": "<string>"
        },
        "kind": "promotional",
        "status": "pending_payment",
        "vatTiming": "at_purchase",
        "tax": {
          "category": "standard",
          "rate": 7.5,
          "inclusive": true
        },
        "denomination": {
          "kind": "money",
          "code": "NGN"
        },
        "currency": "NGN",
        "amount": 2000,
        "remaining": 1500,
        "expiresAt": "2023-11-07T05:31:56Z",
        "expired": true,
        "reason": "<string>",
        "invoice": {
          "id": "<string>",
          "number": "<string>"
        },
        "customData": {},
        "activatedAt": "2023-11-07T05:31:56Z",
        "createdAt": "2023-11-07T05:31:56Z",
        "transactions": [
          {
            "type": "grant",
            "amount": 123,
            "invoice": {
              "id": "<string>",
              "number": "<string>"
            },
            "invoiceLineId": 123,
            "creditNote": {
              "id": "<string>",
              "number": "<string>"
            },
            "reason": "<string>",
            "createdAt": "2023-11-07T05:31:56Z"
          }
        ]
      }
    ]
  }
}

{
  "error": {
    "type": "request_error",
    "code": "authentication_failed",
    "detail": "<string>",
    "errors": [
      {
        "field": "<string>",
        "message": "<string>"
      }
    ]
  },
  "meta": {
    "requestId": "req_550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "type": "request_error",
    "code": "authentication_failed",
    "detail": "<string>",
    "errors": [
      {
        "field": "<string>",
        "message": "<string>"
      }
    ]
  },
  "meta": {
    "requestId": "req_550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "type": "request_error",
    "code": "authentication_failed",
    "detail": "<string>",
    "errors": [
      {
        "field": "<string>",
        "message": "<string>"
      }
    ]
  },
  "meta": {
    "requestId": "req_550e8400-e29b-41d4-a716-446655440000"
  }
}

Credits

Sell prepaid credit

Sells a customer prepaid credit: a credit pack (priceId, a one-time price on a product with kind: credit) or a custom amount. It issues a top-up invoice (billingReason: credit_purchase) and the lots it pays for, pending_payment until the invoice is paid. Manual collection (the default) returns the invoice with its hostedUrl; automatic collection charges paymentMethod, or the customer’s default card. A voided top-up cancels its lots.

When VAT is charged comes from vatTiming, else the pack’s product, else your team default; a purchase that resolves to none is refused.

at_redemption: the top-up carries no VAT and is numbered in its own -PP- sequence. The credit is spent after tax, like cash, and VAT is charged on what it pays for.
at_purchase: the top-up is a normal tax invoice in your invoice sequence, taxed by the pack’s product’s tax category (or taxCategory for a custom amount) with VAT included or added on top as your prices are. The lot holds what was bought before VAT and is spent before tax, only on lines with the same tax category and rate, so the usage it covers isn’t taxed again.

Expiry comes from expiresAfterMonths (send null for never), else the pack’s product; it counts from payment. A bonus pack, or creditAmount above amount, gives the extra as its own promotional lot with no VAT, spent first and forfeited if the top-up is refunded or charged back. A refund is capped at the credit not yet spent; for at_purchase that is the unspent credit plus its VAT, which the credit note reverses at the top-up’s rate.

Needs credits:write on a restricted key. Emits credit_grant.created for each lot, then credit_grant.updated when the invoice is paid.

POST

customers

{customer}

credit-purchases

Sell prepaid credit

curl --request POST \
  --url https://bouclay.com/api/v1/customers/{customer}/credit-purchases \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "priceId": "price_123",
  "amount": 10000,
  "currency": "NGN",
  "creditAmount": 123,
  "revenueCode": "<string>",
  "expiresAfterMonths": 60,
  "collectionMode": "manual",
  "paymentMethod": "<string>",
  "customData": {}
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    priceId: 'price_123',
    amount: 10000,
    currency: 'NGN',
    creditAmount: 123,
    revenueCode: '<string>',
    expiresAfterMonths: 60,
    collectionMode: 'manual',
    paymentMethod: '<string>',
    customData: {}
  })
};

fetch('https://bouclay.com/api/v1/customers/{customer}/credit-purchases', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://bouclay.com/api/v1/customers/{customer}/credit-purchases"

payload = {
    "priceId": "price_123",
    "amount": 10000,
    "currency": "NGN",
    "creditAmount": 123,
    "revenueCode": "<string>",
    "expiresAfterMonths": 60,
    "collectionMode": "manual",
    "paymentMethod": "<string>",
    "customData": {}
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://bouclay.com/api/v1/customers/{customer}/credit-purchases",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'priceId' => 'price_123',
    'amount' => 10000,
    'currency' => 'NGN',
    'creditAmount' => 123,
    'revenueCode' => '<string>',
    'expiresAfterMonths' => 60,
    'collectionMode' => 'manual',
    'paymentMethod' => '<string>',
    'customData' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "data": {
    "object": "credit_purchase",
    "invoice": {
      "id": "<string>",
      "number": "<string>",
      "status": "<string>",
      "billingReason": "<string>",
      "purpose": "card_verification",
      "collectionMode": "automatic",
      "currency": "<string>",
      "subtotal": 1,
      "grantApplied": 1,
      "taxTotal": 1,
      "taxes": [
        {
          "name": "VAT",
          "rate": 7.5,
          "reason": "<string>",
          "inclusive": true,
          "amount": 1
        }
      ],
      "total": 1,
      "minimumCommitment": {
        "amount": 123,
        "counted": 123,
        "shortfall": 123
      },
      "spendingCap": {
        "amount": 123,
        "counted": 123,
        "takenBack": 123
      },
      "sellerTaxId": "<string>",
      "sellerVatRegistered": true,
      "billingAddress": {},
      "reference": "<string>",
      "amountPaid": 1,
      "amountCredited": 1,
      "balanceApplied": 0,
      "amountDue": 1,
      "paidAt": "2023-11-07T05:31:56Z",
      "customer": {
        "id": "<string>",
        "email": "jsmith@example.com",
        "name": "<string>",
        "taxId": "<string>"
      },
      "subscription": {
        "id": "<string>",
        "status": "<string>",
        "pauseReason": "requested"
      },
      "payment": {
        "id": "<string>",
        "status": "pending",
        "amount": 1,
        "amountRefunded": 1,
        "amountChargedBack": 1,
        "currency": "<string>",
        "failureCode": "<string>",
        "failureReason": "<string>",
        "attemptNumber": 123,
        "manualMethod": "cash",
        "reference": "<string>",
        "processedAt": "2023-11-07T05:31:56Z",
        "invoice": {
          "id": "<string>"
        },
        "customer": {
          "id": "<string>"
        },
        "createdAt": "2023-11-07T05:31:56Z"
      },
      "dueAt": "2023-11-07T05:31:56Z",
      "hostedUrl": "<string>",
      "invoicePdfUrl": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "lines": [
        {
          "id": 123,
          "description": "<string>",
          "kind": "plan",
          "quantity": 123,
          "unitAmount": 1,
          "quantityLabel": "<string>",
          "tierBreakdown": "<string>",
          "total": 1,
          "billingTiming": "advance",
          "periodStart": "2023-11-07T05:31:56Z",
          "periodEnd": "2023-11-07T05:31:56Z",
          "usageQuantity": 123,
          "taxCategory": "standard",
          "revenueCode": "<string>",
          "discountAmount": 1,
          "grantApplied": 1,
          "taxAmount": 1,
          "taxRate": 7.5,
          "taxName": "VAT",
          "taxReason": "export of services",
          "taxInclusive": true
        }
      ]
    },
    "grants": [
      {
        "id": "cg_123",
        "object": "credit_grant",
        "customer": {
          "id": "<string>"
        },
        "kind": "promotional",
        "status": "pending_payment",
        "vatTiming": "at_purchase",
        "tax": {
          "category": "standard",
          "rate": 7.5,
          "inclusive": true
        },
        "denomination": {
          "kind": "money",
          "code": "NGN"
        },
        "currency": "NGN",
        "amount": 2000,
        "remaining": 1500,
        "expiresAt": "2023-11-07T05:31:56Z",
        "expired": true,
        "reason": "<string>",
        "invoice": {
          "id": "<string>",
          "number": "<string>"
        },
        "customData": {},
        "activatedAt": "2023-11-07T05:31:56Z",
        "createdAt": "2023-11-07T05:31:56Z",
        "transactions": [
          {
            "type": "grant",
            "amount": 123,
            "invoice": {
              "id": "<string>",
              "number": "<string>"
            },
            "invoiceLineId": 123,
            "creditNote": {
              "id": "<string>",
              "number": "<string>"
            },
            "reason": "<string>",
            "createdAt": "2023-11-07T05:31:56Z"
          }
        ]
      }
    ]
  }
}

{
  "error": {
    "type": "request_error",
    "code": "authentication_failed",
    "detail": "<string>",
    "errors": [
      {
        "field": "<string>",
        "message": "<string>"
      }
    ]
  },
  "meta": {
    "requestId": "req_550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "type": "request_error",
    "code": "authentication_failed",
    "detail": "<string>",
    "errors": [
      {
        "field": "<string>",
        "message": "<string>"
      }
    ]
  },
  "meta": {
    "requestId": "req_550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "type": "request_error",
    "code": "authentication_failed",
    "detail": "<string>",
    "errors": [
      {
        "field": "<string>",
        "message": "<string>"
      }
    ]
  },
  "meta": {
    "requestId": "req_550e8400-e29b-41d4-a716-446655440000"
  }
}

Authorizations

Authorization

string

header

required

Use a Bouclay secret key (sk_test_..., sk_live_...) or restricted key (rk_test_..., rk_live_...).

A secret key can call every endpoint. A restricted key can only call the endpoints its scopes cover. A scope is {resource}:{access}, for example customers:read or refunds:write, and write includes read. GET requests need read access and everything else needs write, except POST /subscriptions/{id}/items/{item}/preview, which only needs subscriptions:read. A request outside the key's scopes gets 403 permission_denied naming the missing scope, and its Idempotency-Key is not used up.

Resource	Endpoints	Access
`customers`	customers, their addresses and payment methods	read, write
`entitlements`	`/customers/{id}/entitlements`	read
`credits`	`/customers/{id}/credit-balance`, credit purchases, credit grants, auto-reloads, credit holds (committing one records its usage)	read, write
`catalog`	products, plans, prices	read, write
`meters`	meters	read, write
`usage`	meter events, `/customers/{id}/usage`	read, write
`discounts`	discounts	read
`subscriptions`	subscriptions	read, write
`invoices`	invoices	read, write
`credit_notes`	credit notes, `POST /invoices/{id}/credit-notes` (a refund to the card also needs `refunds:write`)	read, write
`payments`	payments	read
`refunds`	refunds, `POST /payments/{id}/refunds`, chargebacks and their outcome	read, write
`checkout_sessions`	checkout sessions	read, write
`portal_sessions`	portal sessions	write
`events`	events	read
`webhook_endpoints`	webhook endpoints	read, write
`metrics`	metrics	read

Publishable keys (pk_...) are rejected by server-side API endpoints. A key's mode scopes what it can see and charge: a test key can never reach a live card.

Headers

Idempotency-Key

string

required

Required for POST and PATCH requests. Replays identical method + path + body requests and rejects mismatched re-use.

Required string length: 1 - 255

Path Parameters

customer

string

required

Body

application/json

priceId

string

A credit pack. Leave out amount, currency and creditAmount.

Example:

"price_123"

amount

number

What the customer pays, in major units of currency (before VAT added on top, for at_purchase when your prices exclude VAT). At least the minimum charge for the currency.

Example:

10000

currency

string

Defaults to the customer's.

Example:

"NGN"

creditAmount

number

The credit received, when more than amount. The difference is a bonus.

vatTiming

enum<string>

at_redemption: no VAT on the top-up, VAT on what the credit pays for. at_purchase: VAT on the top-up, and the credit is spent before tax.

Available options:

at_redemption,

at_purchase

taxCategory

enum<string>

A custom amount's tax category, which taxes an at_purchase top-up and decides the lines its credit may pay. Defaults to standard. A pack uses its product's; leave this out with priceId.

Available options:

standard,

zero_rated,

exempt

revenueCode

string

A custom amount's revenue code, kept on the top-up line. Leave out with priceId.

Maximum string length: 64

expiresAfterMonths

integer | null

Required range: 1 <= x <= 120

collectionMode

enum<string>

default:manual

Available options:

manual,

automatic

paymentMethod

string

A saved card for automatic collection.

customData

object | null

Kept on the prepaid lot.

Response

The top-up invoice and its lots.

data

object

Show child attributes

Overview

Customers

Customer addresses

Entitlements

Credits

Usage

Payment methods

Catalog

Meters

Discounts

Subscriptions

Metrics

Invoices

Credit notes

Payments

Refunds

Chargebacks

Events

Checkout sessions

Portal sessions

Payment links

Webhook endpoints

Sell prepaid credit

Authorizations

Headers

Path Parameters

Body

Response