API reference · Getting paid

Payer

GET/pay/attempt/{reference}Read a payment attempt
POST/pay/attempt/{reference}/cardSubmit a tokenised card against an attempt
POST/pay/attempt/{reference}/mobile-moneyAsk the operator to prompt the payer's handset
GET/pay/code/{shortCode}Read a collection request by its short payment code
POST/pay/escrow/approve/{token}Approve a held payment from the notice
POST/pay/escrow/object/{token}Object to a held payment being released
GET/pay/{reference}Read a collection request as the payer
POST/pay/{reference}/attemptStart a payment attempt on a collection request
POST/pay/{reference}/contactSend the payer a code to prove they control a contact
POST/pay/{reference}/contact/proveProve a contact with the code that was sent to it

GET Read a payment attempt

GET /pay/attempt/{reference}

What the payer's application polls while an authentication step runs in another window. Carries a masked instrument and never anything more.

Headers

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

Path parameters

Name
`reference`

Example

Response: GenericResponseCollectionAttemptResponse

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

{
  "data": {
    "attemptReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "requestReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "railCode": "string",
    "status": "string",
    "amount": "string",
    "currencyCode": "string",
    "maskedInstrument": "string",
    "cardBrand": "string",
    "authenticationRedirectUrl": "string",
    "receiptReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "authorisedAmount": "string",
    "capturedAmount": "string",
    "authorisationExpiresAt": "string",
    "failureReason": "string"
  },
  "description": "Collection attempt retrieved successfully"
}

Responses

Status	When
`200`	Collection attempt retrieved successfully

POST Submit a tokenised card against an attempt

POST /pay/attempt/{reference}/card

The request body has no field that can hold a card number, an expiry or a CVV. The payer typed into the acquirer's hosted field and the application received a token; the token is what arrives here. A decline comes back as a single generic reason - an issuer's precise reason is a card-testing oracle, so it is recorded against the attempt and not returned.

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: SubmitCardRequest · Response: GenericResponseCollectionAttemptResponse

curl -X POST "https://api.bridgemoni.com/pay/attempt/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/card" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
  "instrumentToken": "string",
  "threeDsServerTransactionId": "string",
  "captureImmediately": true
}'

{
  "instrumentToken": "string",
  "threeDsServerTransactionId": "string",
  "captureImmediately": true
}

{
  "data": {
    "attemptReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "requestReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "railCode": "string",
    "status": "string",
    "amount": "string",
    "currencyCode": "string",
    "maskedInstrument": "string",
    "cardBrand": "string",
    "authenticationRedirectUrl": "string",
    "receiptReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "authorisedAmount": "string",
    "capturedAmount": "string",
    "authorisationExpiresAt": "string",
    "failureReason": "string"
  },
  "description": "Card payment submitted successfully"
}

Responses

Status	When
`200`	Card payment submitted successfully

POST Ask the operator to prompt the payer's handset

POST /pay/attempt/{reference}/mobile-money

One prompt per attempt: prompting again would ask the payer to approve a second debit, and an operator that honours both has taken the money twice. The attempt then waits. Our own timer stops showing it as pending after a few minutes, which is a statement about this checkout and not about the payer's wallet - a payer who approves after it fires has sent real money, and that confirmation is still honoured.

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: SubmitMobileMoneyRequest · Response: GenericResponseCollectionAttemptResponse

curl -X POST "https://api.bridgemoni.com/pay/attempt/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/mobile-money" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
  "payerMsisdn": "string"
}'

{
  "payerMsisdn": "string"
}

{
  "data": {
    "attemptReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "requestReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "railCode": "string",
    "status": "string",
    "amount": "string",
    "currencyCode": "string",
    "maskedInstrument": "string",
    "cardBrand": "string",
    "authenticationRedirectUrl": "string",
    "receiptReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "authorisedAmount": "string",
    "capturedAmount": "string",
    "authorisationExpiresAt": "string",
    "failureReason": "string"
  },
  "description": "Payment prompt sent successfully"
}

Responses

Status	When
`200`	Payment prompt sent successfully

GET Read a collection request by its short payment code

GET /pay/code/{shortCode}

For the rails where a person retypes a code rather than following a link - USSD, and a printed QR somebody is reading off a receipt. The code carries a check character, so a single mistyped or transposed character fails here rather than naming somebody else's collection. Every failure returns the same refusal: a malformed code, a code nobody minted, and a code whose request is expired, cancelled or already paid are indistinguishable in the response, because a screen that answered them differently would be a directory of every collection on the platform, walkable one guess at a time.

Headers

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

Path parameters

Name
`shortCode`

Example

Response: GenericResponsePayerProjectionResponse

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

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "collectorDisplayName": "string",
    "requestDescription": "string",
    "status": "string",
    "currencyCode": "string",
    "amountMode": "string",
    "amountPayable": "string",
    "minAmount": "string",
    "maxAmount": "string",
    "surcharge": "string",
    "expiresAt": "string",
    "rails": [
      {
        "railCode": "string",
        "displayName": "string",
        "accountNumber": "string",
        "bankName": "string",
        "accountName": "ADA OKAFOR",
        "shortCode": "string",
        "qrPayload": "string",
        "qrPayloadType": "string"
      }
    ]
  },
  "description": "Collection request retrieved successfully"
}

Responses

Status	When
`200`	Collection request retrieved successfully

POST Approve a held payment from the notice

POST /pay/escrow/approve/{token}

The same token as the objection link, which is why it has to be treated as a payment credential: whoever holds it can release money.

Headers

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

Path parameters

Name
`token`

Example

Response: GenericResponseEscrowObjectionResponse

curl -X POST "https://api.bridgemoni.com/pay/escrow/approve/value" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "gateReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "outcome": "string",
    "gateStatus": "string"
  },
  "description": "Approval recorded successfully"
}

Responses

Status	When
`200`	Approval recorded successfully

POST Object to a held payment being released

POST /pay/escrow/object/{token}

One click from the notice, no account and no reason. A mandatory reason field is a barrier, and a payer who cannot articulate why still gets to say no. The objection moves the gate to the existing dispute path; nothing new adjudicates it. The collector cannot withdraw, dismiss or expire it.

Headers

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

Path parameters

Name
`token`

Example

Response: GenericResponseEscrowObjectionResponse

curl -X POST "https://api.bridgemoni.com/pay/escrow/object/value" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "gateReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "outcome": "string",
    "gateStatus": "string"
  },
  "description": "Objection recorded successfully"
}

Responses

Status	When
`200`	Objection recorded successfully

GET Read a collection request as the payer

GET /pay/{reference}

The payer-facing projection, served to the application the payer is using rather than to the payer. The application authenticates with its own client credentials; the payer needs no Bridge account and holds no session, so nothing here is unauthenticated and nothing here identifies a payer either. It lives under /pay so a checkout application's role can be granted this and nothing else - the collector endpoints under /collection stay out of its reach. Deliberately thin: it carries the collector's display name, what is being asked for and how it can be paid, and nothing else. The fee, the merchant discount rate, the settlement account, the collector's own reference, the metadata and every other payer are absent from the response type itself rather than filtered on the way out.

Headers

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

Path parameters

Name
`reference`

Example

Response: GenericResponsePayerProjectionResponse

curl -X GET "https://api.bridgemoni.com/pay/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",
    "collectorDisplayName": "string",
    "requestDescription": "string",
    "status": "string",
    "currencyCode": "string",
    "amountMode": "string",
    "amountPayable": "string",
    "minAmount": "string",
    "maxAmount": "string",
    "surcharge": "string",
    "expiresAt": "string",
    "rails": [
      {
        "railCode": "string",
        "displayName": "string",
        "accountNumber": "string",
        "bankName": "string",
        "accountName": "ADA OKAFOR",
        "shortCode": "string",
        "qrPayload": "string",
        "qrPayloadType": "string"
      }
    ]
  },
  "description": "Collection request retrieved successfully"
}

Responses

Status	When
`200`	Collection request retrieved successfully

POST Start a payment attempt on a collection request

POST /pay/{reference}/attempt

Reserves an attempt on a chosen rail and hands back whatever the payer's application needs to continue - for a card that is where to collect the card details, which is the acquirer's own hosted field and never Bridge. The return URL is taken from the collection request rather than from this body: a checkout that names its own return address is how an attacker sends an authenticated payer somewhere of their choosing. Several attempts may exist on one request; only one can succeed, because the receipt is what closes the request and there is one of those.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live
`Idempotency-Key`	Reuse the same value on every retry of this request
`Content-Type`	application/json

Path parameters

Name
`reference`

Example

Request body: StartAttemptRequest · Response: GenericResponseCollectionAttemptResponse

curl -X POST "https://api.bridgemoni.com/pay/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/attempt" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "railCode": "string",
  "amount": "string",
  "payerIdentifier": "string"
}'

{
  "railCode": "string",
  "amount": "string",
  "payerIdentifier": "string"
}

{
  "data": {
    "attemptReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "requestReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "railCode": "string",
    "status": "string",
    "amount": "string",
    "currencyCode": "string",
    "maskedInstrument": "string",
    "cardBrand": "string",
    "authenticationRedirectUrl": "string",
    "receiptReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "authorisedAmount": "string",
    "capturedAmount": "string",
    "authorisationExpiresAt": "string",
    "failureReason": "string"
  },
  "description": "Collection attempt started successfully"
}

Responses

Status	When
`200`	Collection attempt started successfully

POST Send the payer a code to prove they control a contact

POST /pay/{reference}/contact

Asked for only where the collection is held behind gates that can release on the payer's silence, and shown with that reason: so we can tell you before your money is released. A contact supplied by the collector never reaches this level however it behaves afterwards, because a collector who can nominate the address we serve can manufacture a silence the payer never had a chance to break.

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: VerifyPayerContactRequest · Response: GenericResponsePayerContactResponse

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

{
  "contact": "string",
  "channel": "string"
}

{
  "data": {
    "requestReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "assurance": "string",
    "provenance": "string",
    "channel": "string",
    "provedAt": "string",
    "permitsSilentRelease": true
  },
  "description": "Verification started successfully"
}

Responses

Status	When
`200`	Verification started successfully

POST Prove a contact with the code that was sent to it

POST /pay/{reference}/contact/prove

Attempts are capped. An unlimited guess count on a six digit code proves nothing about who holds the address.

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: ProvePayerContactRequest · Response: GenericResponsePayerContactResponse

curl -X POST "https://api.bridgemoni.com/pay/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/contact/prove" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "string"
}'

{
  "code": "string"
}

{
  "data": {
    "requestReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "assurance": "string",
    "provenance": "string",
    "channel": "string",
    "provedAt": "string",
    "permitsSilentRelease": true
  },
  "description": "Contact verified successfully"
}

Responses

Status	When
`200`	Contact verified successfully

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