API reference · Accounts & ledger

Payment instruments

POST/instrumentSave something to pay with
GET/instrument/optionsWhat could pay for this
DELETE/instrument/{reference}Remove an instrument
GET/instrument/{reference}One instrument
POST/instrument/{reference}/defaultMake this your default
POST/instrument/{reference}/resumeUse it again
POST/instrument/{reference}/suspendPause an instrument
GET/instrumentsEverything you have saved

POST Save something to pay with

POST /instrument

A wallet is usable straight away - it labels an account you already own, so there is nothing to verify. Anything held elsewhere comes back PENDING_VERIFICATION with what to do next. Never send a card number: cards are captured by the provider and saved here as a token, and anything card-shaped is refused before it is stored.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live
`Content-Type`	application/json

Example

Request body: LinkInstrumentRequest · Response: PaymentInstrumentResponse

curl -X POST "https://api.bridgemoni.com/instrument" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "WALLET",
    "nickname": "Ada Obi",
    "currencyCode": "NGN",
    "countryCode": "text",
    "accountNumber": "0123456789",
    "externalIdentifier": "text",
    "providerCode": "text",
    "financialInstitutionCode": "text",
    "capabilities": [
      "FUND"
    ],
    "token": {
      "tokenReference": "text",
      "scheme": "text",
      "bin": "text",
      "lastFour": "text",
      "expiryMonth": 1,
      "expiryYear": 1,
      "cardholderName": "Ada Obi"
    },
    "cryptoAddress": {
      "networkAssetCode": "text",
      "address": "text",
      "addressMemo": "text",
      "settlementCurrencyCode": "NGN"
    },
    "setAsDefault": {
      "purpose": "ANY",
      "currencyCode": "NGN"
    },
    "tokenReference": "text",
    "scheme": "text",
    "bin": "text",
    "lastFour": "text",
    "expiryMonth": 1,
    "expiryYear": 1,
    "cardholderName": "Ada Obi",
    "networkAssetCode": "text",
    "address": "text",
    "addressMemo": "text",
    "settlementCurrencyCode": "NGN",
    "purpose": "ANY"
  }'

{
  "kind": "WALLET",
  "nickname": "Ada Obi",
  "currencyCode": "NGN",
  "countryCode": "text",
  "accountNumber": "0123456789",
  "externalIdentifier": "text",
  "providerCode": "text",
  "financialInstitutionCode": "text",
  "capabilities": [
    "FUND"
  ],
  "token": {
    "tokenReference": "text",
    "scheme": "text",
    "bin": "text",
    "lastFour": "text",
    "expiryMonth": 1,
    "expiryYear": 1,
    "cardholderName": "Ada Obi"
  },
  "cryptoAddress": {
    "networkAssetCode": "text",
    "address": "text",
    "addressMemo": "text",
    "settlementCurrencyCode": "NGN"
  },
  "setAsDefault": {
    "purpose": "ANY",
    "currencyCode": "NGN"
  },
  "tokenReference": "text",
  "scheme": "text",
  "bin": "text",
  "lastFour": "text",
  "expiryMonth": 1,
  "expiryYear": 1,
  "cardholderName": "Ada Obi",
  "networkAssetCode": "text",
  "address": "text",
  "addressMemo": "text",
  "settlementCurrencyCode": "NGN",
  "purpose": "ANY"
}

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "kind": "WALLET",
    "custody": "INTERNAL",
    "direction": "SOURCE_ONLY",
    "status": "DRAFT",
    "nickname": "Ada Obi",
    "displayIdentifier": "text",
    "displayName": "text",
    "scheme": "text",
    "currencyCode": "text",
    "providerCode": "text",
    "capabilities": [
      "FUND"
    ],
    "defaultFor": [
      {
        "purpose": "ANY",
        "currencyCode": "text"
      }
    ],
    "verification": {
      "method": "text",
      "customerActionType": "text",
      "customerActionUrl": "text",
      "instruction": "text",
      "expiresAt": "2027-03-14T14:30:01",
      "attemptsRemaining": 1
    },
    "warnings": [
      "text"
    ],
    "suspensionReason": "text",
    "createdAt": "2027-03-14T14:30:01"
  },
  "description": "Save something to pay with"
}

Responses

Status	When
`200`	Instrument saved
`400`	A card number was sent, or the kind's own required fields are missing
`403`	The tenant has this kind disabled, or your verification tier is too low
`409`	You have already saved this one

GET What could pay for this

GET /instrument/options

Every instrument you have, with whether it works for this particular payment and - when it does not - a reason you can show without rewording it. Answered from what Bridge already knows, so it is safe to call while rendering a payment screen: no provider is contacted and a balance held elsewhere is reported as last seen or as unknown rather than fetched.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Query parameters

Name	Default
`purpose`	Optional
`capability`	Optional
`currencyCode`	Optional

Example

Response: InstrumentOptionsResponse

curl -X GET "https://api.bridgemoni.com/instrument/options?purpose=value&capability=value&currencyCode=value" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "resolvedDefault": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "options": [
      {
        "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
        "kind": "WALLET",
        "displayIdentifier": "text",
        "nickname": "Ada Obi",
        "eligible": true,
        "ineligibilityCode": "text",
        "ineligibilityReason": "text",
        "settlement": "text",
        "requiresCustomerAction": true,
        "availableBalance": {
          "amount": "250000.00",
          "currencyCode": "NGN"
        },
        "balanceAsOf": "2027-03-14T14:30:01",
        "balanceKnown": true,
        "estimatedFee": {
          "amount": "250000.00",
          "currencyCode": "NGN"
        }
      }
    ]
  },
  "description": "What could pay for this"
}

Responses

Status	When
`200`	Instrument options retrieved successfully
`409`	That instrument cannot be used right now

DELETE Remove an instrument

DELETE /instrument/{reference}

Permanent, and it stops being usable immediately. The record itself is kept, because a payment that has already settled must always be able to name what paid for it - so this does not erase your history. You can save the same instrument again later.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`reference`

Example

Response: Void

curl -X DELETE "https://api.bridgemoni.com/instrument/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "description": "Remove an instrument"
}

Responses

Status	When
`200`	Instrument removed successfully
`404`	Instrument not found

GET One instrument

GET /instrument/{reference}

Identifiers come back masked. There is no form of this call that returns them in full.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`reference`

Example

Response: PaymentInstrumentResponse

curl -X GET "https://api.bridgemoni.com/instrument/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "kind": "WALLET",
    "custody": "INTERNAL",
    "direction": "SOURCE_ONLY",
    "status": "DRAFT",
    "nickname": "Ada Obi",
    "displayIdentifier": "text",
    "displayName": "text",
    "scheme": "text",
    "currencyCode": "text",
    "providerCode": "text",
    "capabilities": [
      "FUND"
    ],
    "defaultFor": [
      {
        "purpose": "ANY",
        "currencyCode": "text"
      }
    ],
    "verification": {
      "method": "text",
      "customerActionType": "text",
      "customerActionUrl": "text",
      "instruction": "text",
      "expiresAt": "2027-03-14T14:30:01",
      "attemptsRemaining": 1
    },
    "warnings": [
      "text"
    ],
    "suspensionReason": "text",
    "createdAt": "2027-03-14T14:30:01"
  },
  "description": "One instrument"
}

Responses

Status	When
`404`	No such instrument, or it is not yours - the two are deliberately the same answer

POST Make this your default

POST /instrument/{reference}/default

Defaults are per currency and per purpose, so "my card for bills, my wallet for everything else" is two settings rather than one compromise. A default that later stops working is skipped at payment time rather than failing the payment, so a stale preference can never lock you out.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live
`Content-Type`	application/json

Path parameters

Name
`reference`

Example

Request body: SetInstrumentDefaultRequest · Response: PaymentInstrumentResponse

curl -X POST "https://api.bridgemoni.com/instrument/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/default" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "ANY",
    "currencyCode": "NGN"
  }'

{
  "purpose": "ANY",
  "currencyCode": "NGN"
}

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "kind": "WALLET",
    "custody": "INTERNAL",
    "direction": "SOURCE_ONLY",
    "status": "DRAFT",
    "nickname": "Ada Obi",
    "displayIdentifier": "text",
    "displayName": "text",
    "scheme": "text",
    "currencyCode": "text",
    "providerCode": "text",
    "capabilities": [
      "FUND"
    ],
    "defaultFor": [
      {
        "purpose": "ANY",
        "currencyCode": "text"
      }
    ],
    "verification": {
      "method": "text",
      "customerActionType": "text",
      "customerActionUrl": "text",
      "instruction": "text",
      "expiresAt": "2027-03-14T14:30:01",
      "attemptsRemaining": 1
    },
    "warnings": [
      "text"
    ],
    "suspensionReason": "text",
    "createdAt": "2027-03-14T14:30:01"
  },
  "description": "Make this your default"
}

Responses

Status	When
`200`	Default instrument set successfully
`404`	Instrument not found
`409`	That instrument cannot be used right now

POST Use it again

POST /instrument/{reference}/resume

Returns it to whatever it was before it was paused - which is not always usable. An instrument paused while it was still being verified goes back to being verified.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`reference`

Example

Response: PaymentInstrumentResponse

curl -X POST "https://api.bridgemoni.com/instrument/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/resume" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "kind": "WALLET",
    "custody": "INTERNAL",
    "direction": "SOURCE_ONLY",
    "status": "DRAFT",
    "nickname": "Ada Obi",
    "displayIdentifier": "text",
    "displayName": "text",
    "scheme": "text",
    "currencyCode": "text",
    "providerCode": "text",
    "capabilities": [
      "FUND"
    ],
    "defaultFor": [
      {
        "purpose": "ANY",
        "currencyCode": "text"
      }
    ],
    "verification": {
      "method": "text",
      "customerActionType": "text",
      "customerActionUrl": "text",
      "instruction": "text",
      "expiresAt": "2027-03-14T14:30:01",
      "attemptsRemaining": 1
    },
    "warnings": [
      "text"
    ],
    "suspensionReason": "text",
    "createdAt": "2027-03-14T14:30:01"
  },
  "description": "Use it again"
}

Responses

Status	When
`200`	Instrument resumed successfully
`404`	Instrument not found

POST Pause an instrument

POST /instrument/{reference}/suspend

Reversible. Nothing is lost and resuming puts it back exactly as it was.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`reference`

Example

Response: PaymentInstrumentResponse

curl -X POST "https://api.bridgemoni.com/instrument/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/suspend" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "kind": "WALLET",
    "custody": "INTERNAL",
    "direction": "SOURCE_ONLY",
    "status": "DRAFT",
    "nickname": "Ada Obi",
    "displayIdentifier": "text",
    "displayName": "text",
    "scheme": "text",
    "currencyCode": "text",
    "providerCode": "text",
    "capabilities": [
      "FUND"
    ],
    "defaultFor": [
      {
        "purpose": "ANY",
        "currencyCode": "text"
      }
    ],
    "verification": {
      "method": "text",
      "customerActionType": "text",
      "customerActionUrl": "text",
      "instruction": "text",
      "expiresAt": "2027-03-14T14:30:01",
      "attemptsRemaining": 1
    },
    "warnings": [
      "text"
    ],
    "suspensionReason": "text",
    "createdAt": "2027-03-14T14:30:01"
  },
  "description": "Pause an instrument"
}

Responses

Status	When
`200`	Instrument suspended successfully
`404`	Instrument not found

GET Everything you have saved

GET /instruments

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Example

Response: List<PaymentInstrumentResponse>

curl -X GET "https://api.bridgemoni.com/instruments" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": [
    {
      "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
      "kind": "WALLET",
      "custody": "INTERNAL",
      "direction": "SOURCE_ONLY",
      "status": "DRAFT",
      "nickname": "Ada Obi",
      "displayIdentifier": "text",
      "displayName": "text",
      "scheme": "text",
      "currencyCode": "text",
      "providerCode": "text",
      "capabilities": [
        "FUND"
      ],
      "defaultFor": [
        {
          "...": "nested"
        }
      ],
      "verification": {
        "method": "text",
        "customerActionType": "text",
        "customerActionUrl": "text",
        "instruction": "text",
        "expiresAt": "2027-03-14T14:30:01",
        "attemptsRemaining": 1
      },
      "warnings": [
        "text"
      ],
      "suspensionReason": "text",
      "createdAt": "2027-03-14T14:30:01"
    }
  ],
  "description": "Everything you have saved"
}

Generated from the OpenAPI document. Branch on the HTTP status: there is no machine-readable error code on the wire. Errors