Documentation Powered by ReDoc

CentroWallet (1.0.22)

Download OpenAPI specification:Download

CentroWallet service.

Authentication

MerchantApiKey

Merchant API key provided in the Authorization header, with a "clientId" parameter in the body.

Security Scheme Type API Key
Header parameter name: Authorization

AccessToken

Authorization via Access Token from endpoint POST /api/v1/auth

Security Scheme Type HTTP
HTTP Authorization Scheme bearer

User

Get list of users with sort/limit + pagination

Returns list of users with sort/limit + pagination

Authorizations:
MerchantApiKey
query Parameters
email
string

Email or part of email

externalUserId
string

External user ID

isActivated
boolean

Is activated user card

isBlocked
boolean

Is blocked user card

limit
integer

Maximum number of transactions to return

page
integer

Page number of transactions to return

orderColumn
string

Column to order the transactions by

orderDirection
string

Direction to order the transactions by (ASC or DESC)

dateFrom
string <date>

Start date of the transactions to filter by

dateTo
string <date>

End date of the transactions to filter by

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "links": {
    },
  • "meta": {
    }
}

Create a user

The endpoint creates a user in CentroWallet along with additional parameters for authorization (such as creating a "user" on the authorization server, an "oauth client" for this authentication backend user, etc).

An additional parameter that could be sent is paymentAccounts, and in this case, a payment account will be created.

Important! The "oauthUrl" parameter contains customer authorization data. The merchant needs to use a library to generate a QR code with the data from this parameter.

Authorizations:
MerchantApiKey
Request Body schema: application/json
email
required
string <email>

User email

type
string

User type

isActivated
boolean

Activate user card

isBlocked
boolean

Block user card (all requests will be blocked)

externalUserId
required
string

External user ID (User ID in merchant system)

Array of objects

Responses

Request samples

Content type
application/json
{
  • "email": "[email protected]",
  • "type": "string",
  • "isActivated": true,
  • "isBlocked": true,
  • "externalUserId": "string",
  • "paymentAccounts": [
    ]
}

Response samples

Content type
application/json
{
  • "userId": 17,
  • "email": "[email protected]",
  • "type": "some-user-type",
  • "activated": true,
  • "blocked": false,
  • "oauthUrl": "otpauth://totp/Centro%20Wallet:fake23%40email.com?secret=LZO4ZUG2XGJG4AWMZ3KR6FDFBQC2EX7L&issuer=Centro%20Wallet&algorithm=SHA1&digits=6&period=30",
  • "paymentAccounts": {
    }
}

Get information about user card

Returns information about user card

Authorizations:
MerchantApiKey

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "uuid": "2fbcccc7-b3a6-3f88-975b-68f96a8e4a4c",
  • "email": "[email protected]",
  • "type": "some_user_type",
  • "externalUserId": "846814538",
  • "isActivated": true,
  • "isBlocked": true,
  • "createdAt": {
    },
  • "updatedAt": {
    },
  • "blockedAt": null
}

Update user

The endpoint updates information about the user's card.

Authorizations:
MerchantApiKey
path Parameters
id
required
integer

User ID

Request Body schema: application/json
One of
isActivated
required
boolean

Activate user card

isBlocked
boolean

Block user card (all requests will be blocked)

type
string

User type

externalUserId
string

External user ID (User ID in merchant system)

Responses

Request samples

Content type
application/json
{
  • "isActivated": true,
  • "isBlocked": true,
  • "type": "string",
  • "externalUserId": "string"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "uuid": "2fbcccc7-b3a6-3f88-975b-68f96a8e4a4c",
  • "email": "[email protected]",
  • "type": "some_user_type",
  • "externalUserId": 846814538,
  • "isActivated": true,
  • "isBlocked": true,
  • "createdAt": {
    },
  • "updatedAt": {
    },
  • "blockedAt": null
}

Restore access

The endpoint makes a request to the authorization server and regenerates the URL for the Authenticator.

Important! The "oauthUrl" parameter contains customer authorization data. The merchant needs to use a library to generate a QR code with the data from this parameter.

Authorizations:
MerchantApiKey
path Parameters
id
required
integer

User ID

Responses

Response samples

Content type
application/json
{
  • "userId": 17,
  • "email": "[email protected]",
  • "activated": true,
  • "blocked": false,
  • "oauthUrl": "otpauth://totp/Centro%20Wallet:fake23%40email.com?secret=LZO4ZUG2XGJG4AWMZ3KR6FDFBQC2EX7L&issuer=Centro%20Wallet&algorithm=SHA1&digits=6&period=30"
}

Generate new auth keys

Endpoint for obtaining a new pair of accessToken and refreshToken based on the provided refreshToken.

Important! This endpoint uses if you plan to use authorization via clients access/refresh tokens

path Parameters
id
required
integer
Request Body schema: application/json
refreshToken
string

The refresh token

Responses

Request samples

Content type
application/json
{
  • "refreshToken": "string"
}

Response samples

Content type
application/json
{
  • "tokenType": "string",
  • "expiresIn": 0,
  • "accessToken": "string",
  • "refreshToken": "string"
}

Authorize

Authorizes the user by email and code from the Authenticator and returns tokens (access token and refresh token) for making requests on behalf of the customer.

Important! This endpoint uses if you plan to use authorization via clients access/refresh tokens

Request Body schema: application/json
email
required
string <email>

Email of the user to authorize

code
required
string 6 characters

Code from the Authenticator app (TOTP token)

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "tokenType": "string",
  • "expiresIn": 0,
  • "accessToken": "string",
  • "refreshToken": "string"
}

Payment Account

Get list of payment accounts

Returns a list of customer payment accounts based on the filters provided in the request.

Authorizations:
MerchantApiKeyAccessToken
query Parameters
clientId
required
string

Client ID. * Required for authorization via MerchantApiKey

system
string

Payment system which uses for PA

currency
string

Payment account currency

isActive
boolean

Activate payment account

isAutoReload
boolean

Enable auto reload payment account

isNotify
boolean

Enable notification about low balance

type
string

Payment account type

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new payment account

Creates a new payment account based on the data from the request.

Authorizations:
MerchantApiKeyAccessToken
Request Body schema: application/json
clientId
required
integer

Client ID. * Required for authorization via MerchantApiKey

method
required
string

Payment method

system
required
string

Payment system

currency
required
string

Currency

name
string

Payment account name

description
string

Payment account description

type
string
Default: "fiat"
Enum: "fiat" "promo"

Payment account type

webhookUrl
string

Default webhook URL for payment account

Responses

Request samples

Content type
application/json
{
  • "clientId": 0,
  • "method": "string",
  • "system": "string",
  • "currency": "string",
  • "name": "string",
  • "description": "string",
  • "type": "fiat",
  • "webhookUrl": "string"
}

Response samples

Content type
application/json
{
  • "id": "3",
  • "uuid": "58b214bf-3fae-40b6-ad19-8c5424892135",
  • "user_id": 10,
  • "name": "some payment account name",
  • "type": "some payment account type",
  • "description": "some description",
  • "balance": 5.33,
  • "currency": "USD",
  • "method": "card",
  • "account_number": "223344****6804",
  • "brand": "mastercard",
  • "expiration_month": 2,
  • "expiration_year": 28,
  • "is_active": true,
  • "autoreload": false,
  • "autoreload_amount": 1.23,
  • "autoreload_min_amount": 1.23,
  • "is_notify": true,
  • "notify_amount": 2.34,
  • "created_at": {
    },
  • "updated_at": {
    },
  • "last_used": {
    },
  • "payment_system": "centrobill",
  • "webhook_url": "https://some-site.io/webhook"
}

Get information about payment account

Returns information about customer payment account.

Authorizations:
MerchantApiKeyAccessToken
path Parameters
id
required
integer

Payment account ID

query Parameters
clientId
required
string

Client ID. * Required for authorization via MerchantApiKey

Responses

Response samples

Content type
application/json
{
  • "id": "3",
  • "uuid": "58b214bf-3fae-40b6-ad19-8c5424892135",
  • "user_id": 10,
  • "name": "some payment account name",
  • "type": "some payment account type",
  • "description": "some description",
  • "balance": 5.33,
  • "currency": "USD",
  • "method": "card",
  • "account_number": "223344****6804",
  • "brand": "mastercard",
  • "expiration_month": 2,
  • "expiration_year": 28,
  • "is_active": true,
  • "autoreload": false,
  • "autoreload_amount": 1.23,
  • "autoreload_min_amount": 1.23,
  • "is_notify": true,
  • "notify_amount": 2.34,
  • "created_at": {
    },
  • "updated_at": {
    },
  • "last_used": {
    },
  • "payment_system": "centrobill",
  • "webhook_url": "https://some-site.io/webhook"
}

Update payment account

Updates information about customer payment account based on data from request.

Authorizations:
MerchantApiKeyAccessToken
path Parameters
id
required
integer
Request Body schema: application/json
clientId
required
integer

Client ID. * Required for authorization via MerchantApiKey

name
string

Payment account name

description
string

Payment account description

isActive
boolean

Payment account active status

isAutoReload
boolean

Payment account auto reload status

autoReloadAmount
number <float>

Auto reload amount

autoReloadMinAmount
number <float>

Auto reload minimum amount

isNotify
boolean

Notify status

notifyAmount
number <float>

Notify amount

webhookUrl
string

Default webhook URL for payment account

Responses

Request samples

Content type
application/json
{
  • "clientId": 0,
  • "name": "string",
  • "description": "string",
  • "isActive": true,
  • "isAutoReload": true,
  • "autoReloadAmount": 0,
  • "autoReloadMinAmount": 0,
  • "isNotify": true,
  • "notifyAmount": 0,
  • "webhookUrl": "string"
}

Response samples

Content type
application/json
{
  • "id": "3",
  • "uuid": "58b214bf-3fae-40b6-ad19-8c5424892135",
  • "user_id": 10,
  • "name": "some payment account name",
  • "type": "some payment account type",
  • "description": "some description",
  • "balance": 5.33,
  • "currency": "USD",
  • "method": "card",
  • "account_number": "223344****6804",
  • "brand": "mastercard",
  • "expiration_month": 2,
  • "expiration_year": 28,
  • "is_active": true,
  • "autoreload": false,
  • "autoreload_amount": 1.23,
  • "autoreload_min_amount": 1.23,
  • "is_notify": true,
  • "notify_amount": 2.34,
  • "created_at": {
    },
  • "updated_at": {
    },
  • "last_used": {
    },
  • "payment_system": "centrobill",
  • "webhook_url": "https://some-site.io/webhook"
}

Refill payment account

The endpoint creates a request for refilling the payment account balance.

Authorizations:
MerchantApiKeyAccessToken
path Parameters
id
required
integer

ID of the payment account to refill

Request Body schema: application/json
clientId
required
integer

Client ID. * Required for authorization via MerchantApiKey

name
required
string

Name of the refill request

amount
required
number

Amount to refill the payment account balance

object
emailOptions
boolean

Whether to send email notifications

redirectUrl
string <uri>

URL to redirect after the refill request is processed

webhookUrl
string <uri>

URL for sending webhook with information about result of operation

secure
boolean

Is need 3D secure check

test
boolean

Is test transaction

merchantOrderId
string

Merchant order ID

metadata
string

Metadata

forceCheckout
boolean

Is need to force Checkout instead Quick sale

Responses

Request samples

Content type
application/json
{
  • "clientId": 0,
  • "name": "string",
  • "amount": 0,
  • "consumer": {
    },
  • "emailOptions": true,
  • "redirectUrl": "http://example.com",
  • "webhookUrl": "http://example.com",
  • "secure": true,
  • "test": true,
  • "merchantOrderId": "string",
  • "metadata": "string",
  • "forceCheckout": true
}

Response samples

Content type
application/json
{}

Top up payment account via NON fiat money

The endpoint adds extra money to customers wallet (NON fiat money)

Authorizations:
MerchantApiKeyAccessToken
path Parameters
id
required
integer

ID of the payment account to top-up

Request Body schema: application/json
clientId
required
integer

Client ID. * Required for authorization via MerchantApiKey

reason
string

Reason for the top-up

amount
required
float

Amount for adding to the customer's wallet

merchantOrderId
string

Merchant order ID

metadata
string

Metadata

dateExpire
date <Y-m-d H:i:s>

Date when virtual transaction will be expired. IMPORTANT! This parameter is available for payment account with type "PROMO".

Responses

Request samples

Content type
application/json
{
  • "clientId": 35,
  • "reason": "test income",
  • "amount": 2.45,
  • "merchantOrderId": "112233",
  • "metadata": "some metadata"
}

Response samples

Content type
application/json
{
  • "id": 274,
  • "userId": 35,
  • "type": "income",
  • "isVirtual": true,
  • "price": 2.45,
  • "balance": 14.99,
  • "currency": "USD",
  • "mode": "charge_virtual",
  • "action": "charge",
  • "status": "success",
  • "merchantOrderId": "112233",
  • "metadata": "some metadata",
  • "message": "test income",
  • "dateExpire": {
    }
}

Transfer money

The endpoint transfer money from one payment account to another.

Important: sender payment account and recipient payment account should have the same currency and have the same merchant

Authorizations:
MerchantApiKeyAccessToken
path Parameters
id
required
integer

ID of the payment account which sends money (sender)

Request Body schema: application/json
clientId
required
integer

Client ID. * Required for authorization via MerchantApiKey

recipientPaymentAccountId
required
integer

ID of the payment account which receive money (recipient)

reason
string

Reason for the top-up

amount
required
float

Transfer amount in format XX.YY

merchantOrderId
string

Merchant order ID

metadata
string

Metadata

Responses

Request samples

Content type
application/json
{
  • "clientId": 35,
  • "recipientPaymentAccountId": 59,
  • "reason": "test transfer",
  • "amount": 0.11,
  • "merchantOrderId": "some order id 123",
  • "metadata": "some metadata"
}

Response samples

Content type
application/json
Example
success
success
failure
{
  • "id": 346,
  • "uuid": "6d4050b6-e99f-4c8d-b085-77fa723b70b5",
  • "userId": 35,
  • "senderPaymentAccountId": 58,
  • "recipientPaymentAccountId": 59,
  • "type": "outcome",
  • "price": 0.11,
  • "balance": 12.33,
  • "currency": "USD",
  • "action": "deposit",
  • "mode": "wallet",
  • "status": "success",
  • "merchantOrderId": "some order id 123",
  • "metadata": "some metadata",
  • "message": "test transfer",
  • "createdAt": {
    }
}

Payment

Make payment

Makes payment from users payment account.

IMPORTANT! transaction currency should be the same as a wallet currency

Authorizations:
MerchantApiKeyAccessToken
Request Body schema: application/json
clientId
required
integer

Client ID. * Required for authorization via MerchantApiKey

paymentAccountId
required
integer

ID of the payment account to make the payment from

amount
required
number

Amount to pay

currency
required
string

Currency of the payment

name
required
string

Name of the payment

merchantOrderId
required
string

Merchant order ID

metadata
string

Metadata

webhookUrl
url

Webhook url for sending result about operation

Responses

Request samples

Content type
application/json
{
  • "clientId": 35,
  • "paymentAccountId": 58,
  • "amount": 0.01,
  • "currency": "USD",
  • "name": "test name",
  • "merchantOrderId": "some order id 123",
  • "metadata": "some metadata",
  • "webhookUrl": "https://some.webhook.url?param1=value1"
}

Response samples

Content type
application/json
{
  • "transactionId": 276,
  • "userId": 35,
  • "paymentAccountId": 58,
  • "price": 0.01,
  • "balance": 14.97,
  • "currency": "USD",
  • "merchantOrderId": "some order id 123",
  • "metadata": "some metadata",
  • "status": "success",
  • "action": "deposit",
  • "mode": "wallet",
  • "descriptor": "test name",
  • "message": "Success"
}

Transaction

Get list of customer transactions with sort/limit + pagination

Returns list of customer transactions with sort/limit + pagination

Authorizations:
MerchantApiKeyAccessToken
query Parameters
clientId
required
string

Client ID. * Required for authorization via MerchantApiKey

limit
integer

Maximum number of transactions to return

page
integer

Page number of transactions to return

orderColumn
string
Enum: "created_at" "billing" "payment_method" "external_transaction_id" "currency" "price" "expire_date"

Column to order the transactions by

orderDirection
string
Enum: "asc" "desc"

Direction to order the transactions by (asc or desc)

paymentAccountId
integer

ID of the payment account to filter the transactions by

type
string
Enum: "income" "outcome"

Type of the transactions to filter by (income or outcome)

paymentMethod
string

Payment method to filter the transactions by

virtual
boolean

Whether to filter the transactions by virtual or not

action
string

Action of the transactions to filter by (charge or refund)

mode
string

Mode of the transactions to filter by (wallet or card)

status
string

Status of the transactions to filter by (success or fail)

descriptor
string

Descriptor of the transactions to filter by

merchantOrderId
string

Merchant order ID

dateFrom
string <date>

Start date of the transactions to filter by

dateTo
string <date>

End date of the transactions to filter by

onlyWithExpireDate
boolean

Whether to filter the transactions has non-empty expire date or not

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": [
    ],
  • "meta": {
    }
}

Get information about transaction

Returns information about customer payment account.

Authorizations:
MerchantApiKeyAccessToken
path Parameters
id
required
integer

Transaction ID

query Parameters
clientId
required
string

Client ID. * Required for authorization via MerchantApiKey

Responses

Response samples

Content type
application/json
{
  • "id": 414,
  • "uuid": "40286065-3b54-4a2a-8a90-4fe9552ef252",
  • "userId": 35,
  • "billing": "centrobill",
  • "paymentAccountId": 58,
  • "type": "outcome",
  • "paymentMethod": null,
  • "isVirtual": false,
  • "price": 0.01,
  • "balance": 26.69,
  • "currency": "USD",
  • "action": "deposit",
  • "mode": "wallet",
  • "status": "success",
  • "descriptor": "test name",
  • "merchantOrderID": "112233",
  • "metadata": "{\"test\":\"payment\"}",
  • "accountNumber": "",
  • "brand": "",
  • "expirationMonth": "",
  • "expirationYear": "",
  • "message": "",
  • "code": "",
  • "email": "",
  • "firstname": "",
  • "lastname": "",
  • "country": "",
  • "zip": "",
  • "child": {
    },
  • "date": {
    },
  • "dateExpire": {
    },
  • "balanceTotal": {
    }
}

Void transaction

Makes "void" operation for requested transaction and child transactions.

Authorizations:
MerchantApiKeyAccessToken
path Parameters
id
required
integer

Transaction ID

Request Body schema: application/json
clientId
required
integer

Client ID. * Required for authorization via MerchantApiKey

reason
string

Reason for the top-up

merchantOrderId
string

Merchant order ID

metadata
string

Metadata

Responses

Request samples

Content type
application/json
{
  • "clientId": 35,
  • "reason": "some void reason",
  • "merchantOrderId": "void12345",
  • "metadata": "some metadata"
}

Response samples

Content type
application/json
{
  • "id": 414,
  • "uuid": "40286065-3b54-4a2a-8a90-4fe9552ef252",
  • "userId": 35,
  • "billing": "centrobill",
  • "paymentAccountId": 59,
  • "type": "outcome",
  • "paymentMethod": null,
  • "isVirtual": false,
  • "price": 0.01,
  • "balance": 26.69,
  • "currency": "USD",
  • "action": "deposit",
  • "mode": "wallet",
  • "status": "success",
  • "descriptor": "test name",
  • "merchantOrderID": "112233",
  • "metadata": "{\"test\":\"payment\"}",
  • "accountNumber": "",
  • "brand": "",
  • "expirationMonth": "",
  • "expirationYear": "",
  • "message": "",
  • "code": "",
  • "email": "",
  • "firstname": "",
  • "lastname": "",
  • "country": "",
  • "zip": "",
  • "child": {
    },
  • "date": {
    },
  • "balanceTotal": {
    }
}

Webhook

Webhook on refill request

Returns information about success/failure transaction on refill request

IMPORTANT! Webhook will be sent to the URL from webhookUrl

Responses

Response samples

Content type
application/json
{
  • "id": 491,
  • "uuid": "1e0c7986-c099-49c6-a067-66beffff2d79",
  • "userId": 35,
  • "billing": "centrobill",
  • "paymentAccountId": 80,
  • "type": "income",
  • "paymentMethod": "card",
  • "isVirtual": true,
  • "price": 2.45,
  • "balance": 100.45,
  • "currency": "USD",
  • "action": "charge",
  • "mode": "test",
  • "status": "success",
  • "descriptor": "centrohelp.eu",
  • "merchantOrderID": "orderId1234",
  • "metadata": "some merchant metadata123123",
  • "accountNumber": "411111****1111",
  • "brand": "visa",
  • "expirationMonth": "8",
  • "expirationYear": "28",
  • "message": "Approved",
  • "code": "0",
  • "email": "[email protected]",
  • "firstname": "testName",
  • "lastname": "lastnameName",
  • "country": "DEU",
  • "zip": "12345",
  • "child": [ ],
  • "date": {
    },
  • "balanceTotal": {
    }
}