Send a test bank transfer

POST

/test/transfers

const url = 'https://api.paywithnablr.com/v1/test/transfers';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"account_number":"9912345678"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.paywithnablr.com/v1/test/transfers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "account_number": "9912345678" }'

Test mode only (sk_test_ key). Pays into a test transfer account that the checkout issued, as if the customer had made the transfer. Omit amount to send exactly what was asked; send a different amount to see an amount mismatch. The payment’s outcome then follows the test amount rules.

Authorizations

secretKey

Request Body^required

application/json

object

account_number

required

The account number the checkout showed the customer.

string

amount

Minor units. Omitted or 0 means the exact amount due.

integer format: int64

>= 1

Example

{
  "account_number": "9912345678"
}

Responses

200

The payment after the transfer.

application/json

object

data

required

channel is the method that paid: null until the payment succeeds, never the method of an attempt that failed.

fee, charged_amount and net are exact once the payment has succeeded: the price of the method that paid. Before that they are a quote, and nothing has been charged: the price of the method the customer last chose, or, before they choose, the highest across the methods offered (what the customer pays at most).

object

required

string

object

required

string

Allowed value: payment

reference

required

string

status

required

pending: waiting for the customer. processing: the payment network has the payment and has not confirmed it. succeeded: paid. failed: the checkout closed after the last attempt failed. abandoned: the checkout closed with nothing tried. refunded and partially_refunded are reserved for refunds, which are not yet available.

string

Allowed values: pending processing succeeded failed abandoned refunded partially_refunded

mode

required

string

Allowed values: test live

amount

required

The amount you asked for, in kobo.

integer format: int64

currency

required

string

Allowed values: NGN

fee

required

Our fee, in kobo. Each method’s price is fixed when the payment is created; once succeeded this is the paying method’s fee, before that a quote (see above).

integer format: int64

fee_bearer

required

merchant: the fee comes out of amount. customer: the fee is added to what the customer pays.

string

Allowed values: merchant customer

charged_amount

required

What the customer pays, in kobo. amount, plus fee when the customer bears it. A quote until the payment succeeds.

integer format: int64

net

required

What you receive, in kobo. A quote until the payment succeeds.

integer format: int64

channel

required

One of:

string
null

A payment method. nablr is Pay with Nablr.

string

Allowed values: card bank_transfer ussd nablr

channels

required

The methods the checkout offers.

Array<string>

Allowed values: card bank_transfer ussd nablr

customer

required

object

required

string | null

email

required

string

name

required

string | null

phone

required

string | null

metadata

required

What you sent. {} if you sent nothing.

object

key

additional properties

any

description

required

string | null

callback_url

required

string | null

payment_link_id

required

The payment link this payment came through, if any.

string | null

failure_reason

required

Why the last attempt failed, in words you can show the customer. null once succeeded.

string | null

authorization

required

One of:

object
null

How the payment was made, safe to show. Only the fields that apply are present.

object

brand

Card brand: visa, mastercard or verve.

string

last4

string

exp_month

integer

exp_year

integer

bank

string

nablr_handle

string

paid_at

required

string | null format: date-time

expires_at

required

When the checkout closes.

string format: date-time

settlement

required

The settlement (stl_…) that paid this out, once settled.

string | null

created_at

required

string format: date-time

meta

required

object

request_id

required

This request’s id, also in the X-Request-Id header.

string

Example

{
  "data": {
    "id": "pay_01M3XX8PCBFA5VZ3PQZQ0S78BP",
    "object": "payment",
    "reference": "order_1042",
    "status": "pending",
    "mode": "test",
    "amount": 500000,
    "currency": "NGN",
    "fee": 7500,
    "fee_bearer": "merchant",
    "charged_amount": 500000,
    "net": 492500,
    "channel": "card",
    "channels": [
      "card"
    ],
    "customer": {
      "id": "cus_01M3XX8ERVFY9A1FAQ2EGHYZWT",
      "email": "ada@example.com",
      "name": "Ada Obi"
    },
    "failure_reason": "Your bank declined the card: insufficient funds.",
    "authorization": {
      "brand": "visa",
      "last4": "4081",
      "exp_month": 12,
      "exp_year": 2030,
      "bank": "Nablr Test Bank",
      "nablr_handle": "ada"
    }
  }
}

400

VALIDATION_FAILED: a field is wrong; details says which. A value of the wrong JSON type has detail code type and a message saying what to send (Send a whole number., Send text., Send true or false., Send an object., Send a list.). MALFORMED_REQUEST: the body is not valid JSON.

application/json

object

error

required

object

message

required

A sentence for a person. Safe to show to your user.

string

code

required

string

Allowed values: VALIDATION_FAILED MALFORMED_REQUEST UNAUTHENTICATED INVALID_API_KEY SECRET_KEY_REQUIRED LIVE_MODE_NOT_ENABLED ACCOUNT_RESTRICTED TEST_MODE_ONLY NOT_FOUND METHOD_NOT_ALLOWED CONFLICT DUPLICATE_REFERENCE IDEMPOTENCY_KEY_REUSED REQUEST_IN_PROGRESS INVALID_STATE_TRANSITION PAYLOAD_TOO_LARGE UNSUPPORTED_MEDIA_TYPE RATE_LIMITED INTERNAL_ERROR SERVICE_UNAVAILABLE

title

required

The code in words, for example Validation failed.

string

reference

A quotable reference for some failures.

string

details

One entry per field that is wrong.

Array<object>

object

field

required

string

code

required

For example required, invalid, format, length, unknown, type.

string

message

required

string

meta

Extra context, such as retry_after_seconds on RATE_LIMITED.

object

key

additional properties

any

meta

required

object

request_id

required

This request’s id, also in the X-Request-Id header.

string

Example

{
  "error": {
    "message": "Send a positive amount in minor units (500000 = ₦5,000.00).",
    "code": "VALIDATION_FAILED",
    "title": "Validation failed",
    "details": [
      {
        "field": "amount",
        "code": "invalid",
        "message": "Send a positive amount in minor units (500000 = ₦5,000.00)."
      }
    ]
  },
  "meta": {
    "request_id": "01a0fbd4-3b18-7181-9149-8dbcae100085"
  }
}

401

UNAUTHENTICATED: no Authorization: Bearer header. The message says what to send: your secret key (Bearer sk_test_… or sk_live_…). INVALID_API_KEY: the key is unknown, malformed or revoked.

application/json

object

error

required

object

message

required

A sentence for a person. Safe to show to your user.

string

code

required

string

title

required

The code in words, for example Validation failed.

string

reference

A quotable reference for some failures.

string

details

One entry per field that is wrong.

Array<object>

object

field

required

string

code

required

For example required, invalid, format, length, unknown, type.

string

message

required

string

meta

Extra context, such as retry_after_seconds on RATE_LIMITED.

object

key

additional properties

any

meta

required

object

request_id

required

This request’s id, also in the X-Request-Id header.

string

Example

{
  "error": {
    "message": "The API key provided is not valid.",
    "code": "INVALID_API_KEY",
    "title": "Invalid API key"
  },
  "meta": {
    "request_id": "01a0fbd4-3b68-75e0-bd33-0b950ddc99a5"
  }
}

403

TEST_MODE_ONLY with a live key, or one of the key errors.

application/json

object

error

required

object

message

required

A sentence for a person. Safe to show to your user.

string

code

required

string

title

required

The code in words, for example Validation failed.

string

reference

A quotable reference for some failures.

string

details

One entry per field that is wrong.

Array<object>

object

field

required

string

code

required

For example required, invalid, format, length, unknown, type.

string

message

required

string

meta

Extra context, such as retry_after_seconds on RATE_LIMITED.

object

key

additional properties

any

meta

required

object

request_id

required

This request’s id, also in the X-Request-Id header.

string

Example

{
  "error": {
    "code": "VALIDATION_FAILED",
    "details": [
      {
        "field": "amount"
      }
    ]
  }
}

404

NOT_FOUND: no such object in this mode, or it is not yours.

application/json

object

error

required

object

message

required

A sentence for a person. Safe to show to your user.

string

code

required

string

title

required

The code in words, for example Validation failed.

string

reference

A quotable reference for some failures.

string

details

One entry per field that is wrong.

Array<object>

object

field

required

string

code

required

For example required, invalid, format, length, unknown, type.

string

message

required

string

meta

Extra context, such as retry_after_seconds on RATE_LIMITED.

object

key

additional properties

any

meta

required

object

request_id

required

This request’s id, also in the X-Request-Id header.

string

Example

{
  "error": {
    "message": "This payment could not be found.",
    "code": "NOT_FOUND",
    "title": "Not found"
  },
  "meta": {
    "request_id": "01a0fbd4-5df3-7308-8497-51f8ed8d7c77"
  }
}

429

RATE_LIMITED: wait Retry-After seconds, then retry.

application/json

object

error

required

object

message

required

A sentence for a person. Safe to show to your user.

string

code

required

string

title

required

The code in words, for example Validation failed.

string

reference

A quotable reference for some failures.

string

details

One entry per field that is wrong.

Array<object>

object

field

required

string

code

required

For example required, invalid, format, length, unknown, type.

string

message

required

string

meta

Extra context, such as retry_after_seconds on RATE_LIMITED.

object

key

additional properties

any

meta

required

object

request_id

required

This request’s id, also in the X-Request-Id header.

string

Example

{
  "error": {
    "message": "Too many attempts. Please wait a moment and try again.",
    "code": "RATE_LIMITED",
    "title": "Rate limited",
    "meta": {
      "retry_after_seconds": 12
    }
  },
  "meta": {
    "request_id": "01a0fbd4-3b68-75e0-bd33-0b950ddc99a5"
  }
}

Headers

Retry-After

integer

Seconds to wait.

X-RateLimit-Reset

integer

Unix time when a request will be allowed again.

Send a test bank transfer

Authorizations

Request Bodyrequired

Example

Responses

200

Example

400

Example

401

Example

403

Example

404

Example

429

Example

Headers

Request Body^required