Funding Sources

The funding source object

Attribute

Type

Description

id

uuid

The unique identifier for the funding source.

description

string

The title of the funding source, determined by the user.

meta

string

A JSON object which can store meta data used by the client.

limit_tier

integer

The tier limit (1-5) in which the funding source belongs.

type

FundingSourceType

The funding source type for the funding source.

status

string

The status of the funding source.

active

created expired

frozen

locked

rejected

bank_account

BankAccount

The bank account this funding source connects to.

card

Card

The debit or credit card this funding source connects to.

currencies

array

A list of currencies which the funding source can send and receive funds in.

verified

boolean

Whether the funding source has been verified by the user.

verified_at

time

The time when the funding source was verified, if it has been verified.

created_at

time

The time when the funding source was created.

updated_at

time

The time when the funding source was updated.

Example

{
"id": "46d679a5-c221-4d91-89ee-da7eff58ed21",
"type": "bank_account",
"description": "My funding source",
"meta": "{\"color\": \"blue\"}",
"limit_tier": 1,
"type": {
"id": "46d679a5-c221-4d91-89ee-da7eff58ed21",
"shortcode": "debit_account",
"title": "Debit Account",
"account_type": "bank_account",
"currencies": ["EUR"],
"created_at": "2017-09-04T12:26:43.398646Z",
"updated_at": "2017-09-04T12:26:43.398646Z"
},
"status": "active",
"bank_account": {
"id": "e21dac67-a93f-4681-6572-a6819c747135",
"country": "IS",
"account_number": "053526210380",
"owner_nin": "2103805079",
"enabled": true,
"created_at": "2017-09-04T12:25:53.085206Z",
"updated_at": "2017-09-04T12:25:53.085206Z"
},
"currencies": ["EUR"],
"verified": true,
"verified_at": "2017-09-04T12:26:43.398646Z",
"created_at": "2017-09-04T12:26:43.398646Z",
"updated_at": "2017-09-04T12:26:43.398646Z"
}

The bank object

Attribute

Type

Description

id

uuid

The unique identifier for the bank account.

country

string

Two letter ISO 3166-1 alpha-2 country code representing the country the bank account is located in.

swift

string

SWIFT / BIC code.

iban

string

IBAN bank account number.

account_number

string

A bank specific account number. The format depends on the bank.

routing_number

string

ACH routing number.

name

string

Bank account description or account owner name.

owner_nin

string

An optional unique identifier for the account owner. The format depends on the bank.

meta

string

A JSON object which can store meta data used by the client.

enabled

boolean

Whether the bank account is enabled.

created_at

time

The time when the bank account was created.

updated_at

time

The time when the bank account was updated.

Example

{
"id": "e21dac67-a93f-4681-6572-a6819c747135",
"country": "IS",
"account_number": "053526210380",
"owner_nin": "2103805079",
"meta": "",
"enabled": true,
"created_at": "2017-09-04T12:25:53.085206Z",
"updated_at": "2017-09-04T12:25:53.085206Z"
}

The card object

Attribute

Type

Description

id

uuid

The unique identifier for the card.

type

string

The type of card. debit credit

brand

string

The card brand, e.g. mastercard, visa, etc.

owner_nin

string

An optional unique identifier for the card owner. The format depends on the processor.

expiration_month

integer

Two digit number representing the card's expiration month.

expiration_year

integer

Four digit number representing the card's expiration year.

last_digits

string

The last digits of the card number. The format depends on the processor.

meta

string

A JSON object which can store meta data used by the client.

verified

boolean

Whether the card has been verified.

verified_at

time

The time when the card was verified, if it has been verified.

created_at

time

The time when the bank account was created.

updated_at

time

The time when the bank account was updated.

Example

{
"id": "335563f9-5249-4339-6d31-078e29fd5f04",
"type": "debit",
"brand": "MasterCard",
"owner_nin": "2103805079",
"expiration_month": 10,
"expiration_year": 2020,
"last_digits": "1234",
"meta": "",
"verified": false,
"verified_at": "0001-01-01T00:00:00Z",
"created_at": "2017-09-04T12:25:52.43349Z",
"updated_at": "2017-09-04T12:25:52.43349Z"
}

The balance object

Attribute

Type

Description

id

uuid

The unique identifier for the funding source balance.

amount

float

The difference between amounts deposited to and withdrawn from the funding source in the specific currency.

amount_in

float

The total amount deposited to this funding source in the specific currency.

amount_out

float

The total amount withdrawn from this funding source in the specific currency.

currency

string

Three-letter ISO-4217 code.

created_at

time

The time when the funding source balance was created.

updated_at

time

The time when the funding source balance was updated.

Example

{
"id": "a0bcfb20-99fd-465d-6e23-2e19e8952420",
"amount": 10.0,
"amount_in": 15.0,
"amount_out": 5.0,
"currency": "EUR",
"created_at": "2017-09-04T12:26:43.398646Z",
"updated_at": "2017-09-04T12:26:43.398646Z"
}

Get a list of funding sources

Get a list of all funding sources.

Request
Response
Request

GET /v1/funding_sources

Query Parameters

Name

Type

Description

page

int

Item pagination.

limit

int

Number of items to return per page.

sort

string

Sort the results by created_at, updated_at.

filter

string

Filter the results.

Filtering

Attribute

Type

Operators

Values

owner

boolean

eq

true, false

status

string

eq

active, created, expired, rejected, frozen, locked

type

string

eq

bank_account, card, virtual

Response

200 OK

Returns a list of funding source objects.

Get a funding source

Get a single funding source by ID.

Request
Response
Request

GET /v1/funding_sources/{id}

Response

200 OK

Returns a funding source object.

Get funding source limits and usage

Get a list of transactions for a funding source, both deposits and withdrawals.

Request
Response
Request

GET /v1/funding_sources/{id}/limits

Response

200 OK

[
{
"currency": "EUR",
"limits": [
{
"id": "6e457d7d-996d-4d02-b16c-8ea2ccccadd5",
"title": "Single payment",
"currency": "EUR",
"amount": 10,
"type": {
"id": 1,
"title": "payment"
},
"usage": {
"count": 0,
"amount": 0
},
"period": {
"id": 2,
"title": "single",
"is_rolling_period": false,
"from": "2019-05-13T15:14:36.668538Z",
"to": "2019-05-13T15:14:36.668538Z"
}
}
]
}
]

Get funding source balances

Get a list of balances for a funding source.

Request
Response
Request

GET /v1/funding_sources/{id}/balances

Filtering

Attribute

Type

Operators

Values

currency

string

eq

Three-letter ISO-4217 code. Must be a supported currency.

Response

200 OK

[
{
"id": "a0bcfb20-99fd-465d-6e23-2e19e8952420",
"amount": 10.0,
"amount_in": 15.0,
"amount_out": 5.0,
"currency": "EUR",
"created_at": "2017-09-04T12:26:43.398646Z",
"updated_at": "2017-09-04T12:26:43.398646Z"
}
]

Create a funding source

Create a new funding source. Use either type or type_id to determine the funding source type.

Request
Response
Request

POST /v1/funding_sources

Attribute

Type

Description

description

string

The title of the funding source, only visible to the user. required

type

string

The short code of the funding source type.conditional

type_id

uuid

The ID of the funding source type. conditional

bank_account

BankAccount

If the type is bank_account this object is required.

card

Card

If the type is card this object is required.

BankAccount

Attribute

Type

Description

country

string

Two letter ISO 3166-1 alpha-2 country code representing the country the bank is located in. required

swift

string

The SWIFT code of the bank.

iban

string

The IBAN code of the bank account. This is required if account_number is empty.

account_number

string

The account number of the bank account, in a format which the bank gateway understands. This is required if iban is empty.

routing_number

string

ACH routing number.

name

string

Bank account description or account owner name.

owner_nin

string

An optional unique identifier for the account owner. The format depends on the bank.

Card

Attribute

Type

Description

brand

string

The name of the card brand.

last_digits

string

The last 4 digits of the card number.

expiration_month

integer

Two digit number representing the card's expiration month. required

expiration_year

integer

Four digit number representing the card's expiration year. required

token

string

The tokenized cardholder data used by the card processor gateway. required

owner_nin

string

An optional unique identifier for the card owner. The format depends on the gateway.

Example - Bank account

{
"description": "My Bank Account",
"type": "savings_account",
"bank_account": {
"country": "UK",
"swift": "AAABBCCDDD",
"iban": "GB98MIDL07009312345678",
"account_number": "",
"owner_nin": ""
},
}

Example - Card

{
"description": "My Default Card",
"type": "standard_credit_card",
"card": {
"brand": "MeCard",
"last_digits": "1234",
"expiration_month": 11,
"expiration_year": 2020,
"token": "9724017303484431"
}
}
Response

201 Created

Returns a funding source object.

Update a funding source

Update an existing funding source. If the source is a bank account, only its description can be updated. If the source is a card, its description and expiration date can be updated.

Request
Response
Request

PATCH /v1/funding_sources/{id}

Attribute

Type

Description

description

string

The title of the funding source, only visible to the user.

Card

Attribute

Type

Description

expiration_month

integer

Two digit number representing the card's expiration month.

expiration_year

integer

Four digit number representing the card's expiration year.

Response

200 OK

Returns a funding source object.

Activate funding source

Activate a funding source with user provided data, for example the last 4 digits of a card number.

Request
Response
Request

POST /v1/funding_sources/{id}/activate

Attribute

Type

Description

code

string

User provided activation data.

pin

string

The current user's PIN. required

{
"code": "1234",
"pin": "1234"
}
Response

200 OK

Operation successful.

400 Bad Request

Returns an error from the gateway.

Freeze funding source

Temporarily freeze the funding source, making it unavailable for sending or receiving funds.

Request
Response
Request

POST /v1/funding_sources/{id}/freeze

Attribute

Type

Description

message

string

Optional message.

reason

string

Optional reason (may be required by the gateay). Possible values: damaged, expired, fraud, lost, not_received, other, stolen, unspecified

pin

string

The current user's PIN. required

{
"reason": "lost",
"pin": "1234"
}
Response

200 OK

Operation successful.

400 Bad Request

Returns an error from the gateway.

Lock funding source

Temporarily or permanently lock the funding source, making it unavailable for sending or receiving funds. The severity of this operation depends on the gateway. Most common case is that this will permanently lock the source.

Request
Response
Request

POST /v1/funding_sources/{id}/lock

Attribute

Type

Description

message

string

Optional message.

reason

string

Optional reason (may be required by the gateway). Possible values: damaged, expired, fraud, lost, not_received, other, stolen, unspecified

pin

string

The current user's PIN. required

{
"reason": "stolen",
"pin": "1234"
}
Response

200 OK

Operation successful.

400 Bad Request

Returns an error from the gateway.

Unfreeze funding source

Unfreeze a frozen funding source.

Request
Response
Request

POST /v1/funding_sources/{id}/unfreeze

Attribute

Type

Description

message

string

Optional message.

pin

string

The current user's PIN. required

{
"pin": "1234"
}
Response

200 OK

Operation successful.

400 Bad Request

Returns an error from the gateway.

Unlock funding source

Unlock a locked funding source. Only works if the gateway allows/supports it.

Request
Response
Request

POST /v1/funding_sources/{id}

Attribute

Type

Description

message

string

Optional message.

pin

string

The current user's PIN. required

{
"pin": "1234"
}
Response

200 OK

Operation successful.

400 Bad Request

Returns an error from the gateway.

Verify funding source

Verify a funding source with user provided data, which can, for example, be a code on the user's card statement.

Request
Response
Request

POST /v1/funding_sources/{id}/verify

Attribute

Type

Description

data

string

User provided verification data. required

pin

string

The current user's PIN. required

{
"data": "abc123",
"pin": "1234"
}
Response

200 OK

Operation successful.

400 Bad Request

Returns an error from the gateway.

Request PIN

Allows the user to receive the funding source PIN by some means, such as SMS or email depending on the project. Support for this depends on the gateway.

Request
Response
Request

POST /v1/funding_sources/{id}/pin/request

Attribute

Type

Description

pin

string

The current user's PIN. required

{
"pin": "1234"
}
Response

200 OK

Operation successful.

400 Bad Request

Returns an error from the gateway.

Set PIN

Allows the user to change the funding source PIN. Support for this depends on the gateway.

Request
Response
Request

POST /v1/funding_sources/{id}/pin/set

Attribute

Type

Description

new_pin

string

The new PIN for the funding source. required

pin

string

The current user's PIN. required

{
"new_pin": "1234",
"pin": "1234"
}
Response

200 OK

Operation successful.

400 Bad Request

Returns an error from the gateway.

Delete a funding source

Delete an existing funding source.

Request
Response
Request

DELETE /v1/funding_sources/{id}

Response

200 OK