Record a payment made outside the gateway

curl --request POST \
  --url https://bouclay.com/api/v1/invoices/{invoice}/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "amount": 1,
  "reference": "<string>",
  "paidAt": "2023-11-07T05:31:56Z"
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({amount: 1, reference: '<string>', paidAt: '2023-11-07T05:31:56Z'})
};

fetch('https://bouclay.com/api/v1/invoices/{invoice}/payments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://bouclay.com/api/v1/invoices/{invoice}/payments"

payload = {
    "amount": 1,
    "reference": "<string>",
    "paidAt": "2023-11-07T05:31:56Z"
}
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/invoices/{invoice}/payments",
  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([
    'amount' => 1,
    'reference' => '<string>',
    'paidAt' => '2023-11-07T05:31:56Z'
  ]),
  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": {
    "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
      }
    ]
  },
  "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"
  }
}

Invoices

Record a payment made outside the gateway

Records cash, a bank transfer or POS the customer paid you directly against an open invoice. It pays the invoice like any payment: invoice.updated, the receipt email (naming how it was paid), a past_due subscription made active and a suspension lifted. Nothing is charged. amount must be what the invoice has left to pay (part payments aren’t kept apart yet). Refused for a card check or a payment link’s checkout, which are paid by card. A payment recorded this way is never refunded to a card: give it back with a credit note settled outside. Uses the invoices scope.

POST

invoices

{invoice}

payments

Record a payment made outside the gateway

curl --request POST \
  --url https://bouclay.com/api/v1/invoices/{invoice}/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "amount": 1,
  "reference": "<string>",
  "paidAt": "2023-11-07T05:31:56Z"
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({amount: 1, reference: '<string>', paidAt: '2023-11-07T05:31:56Z'})
};

fetch('https://bouclay.com/api/v1/invoices/{invoice}/payments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://bouclay.com/api/v1/invoices/{invoice}/payments"

payload = {
    "amount": 1,
    "reference": "<string>",
    "paidAt": "2023-11-07T05:31:56Z"
}
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/invoices/{invoice}/payments",
  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([
    'amount' => 1,
    'reference' => '<string>',
    'paidAt' => '2023-11-07T05:31:56Z'
  ]),
  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": {
    "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
      }
    ]
  },
  "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

invoice

string

required

Body

application/json

amount

number | null

required

Major currency units. For example, 15000 means NGN 15,000.

Required range: x >= 0

method

enum<string>

required

Available options:

cash,

bank_transfer,

pos

reference

string | null

A transfer reference or your own receipt number.

Maximum string length: 100

paidAt

string<date-time> | null

When it was paid; now if left out. Not in the future.

Response

Invoice response.

data

object

required

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

Record a payment made outside the gateway

Authorizations

Headers

Path Parameters

Body

Response