Lietuvių

Payment Cards

Informacija Atsiprašome, šis skyrius galimas tik anglų kalba.

This chapter describes managing of user payment cards using Wallet API. Client can create card, get card or cards, relate card to specific account and deposit from card to account.

Special permissions are needed for the client to manage payment cards. Also to manage specific user's cards, scope cards is needed.

Creating card

In order to make further actions with card, it must be initially created.

Request

POST https://wallet.paysera.com/rest/v1/card

Request body structure

Parametras
Tipas
Pastabos
Aprašymas
user_id
integer
required
ID of an user, creating card
accounts
array of Card Account objects, see data structures
optional
Links between card and accounts
relation
Relation object, see data structures
optional
Relation process information. Should contain redirect_back_uri that is used to redirect user after card relation process is finished

Response

Response is a Card data structure, see data structures.

Example request

POST /rest/v1/card HTTP/1.1
Host: wallet.paysera.com
Content-Type: application/json;charset=utf-8
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="IEAxJ4KXzScyq6jX/iSmrQ1sNAf4LI+3hM962VlWPkE=", ext="body_hash=QbSp3xrqzhDpmjuLmGjjmBDdLalG55QEJFX2W1jq3QI%3D"
{
    "user_id": 13,
    "relation": {
        "redirect_back_uri": "http://example.com"
    }
}

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "id": 1,
    "status": "unrelated",
    "user_id": "13",
    "relation": {
        "redirect_uri": "http://www.evp.lt/123abc"
    }
}

After the card was created, no funds can be deposited to account from this card yet. At this moment the card has status unrelated. In order to deposit funds either manually or automatically from this card, card must be related (status related). Relating is a process of confirming that this card is an actual valid card, owned by a user. Unrelated card can still be deleted and edited.

To initiate card relation process, user must be redirected to redirect_uri where she finalizes card creation process - enters sensitive card data and submits it to card processing partner. Partner then accepts or denies card and informs Wallet API. This process is asynchronous, so the client must wait for this process to finish if it wants to deposit funds instantly after card relation. Client can see if process is finished by periodically requesting for previously created card by id and watching if status became related.

Card status can also become failed. It means that card relation processed has for some reason failed.

If client wants user to be redirected to specific uri after card relation process is finished, relation object, containing redirect_back_uri parameter should be provided when creating card.

Editing card

Card editing is actually editing links between cards and accounts. Client cannot edit any other card properties. Card editing is not allowed if it has status failed.

Request

PUT https://wallet.paysera.com/rest/v1/card/:id

Request body structure

Parametras
Tipas
Pastabos
Aprašymas
accounts
array of Card Account objects, see data structures
optional
Links between card and accounts

Response

Response is a Card data structure.

Example request

PUT /rest/v1/card/1 HTTP/1.1
Host: wallet.paysera.com
Content-Type: application/json;charset=utf-8
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="YMx4YhNSCMXpOeH5cqE9CNwwRNDizF86t2dxGEZ2TRY=", ext="body_hash=wUJD0sKavpoVJREyWyu%2FD4sNClbaYUzDksAa79Sldps%3D"
{
    "accounts": [
        {
            "number": "EVP0123456789123",
            "order": 4
        }
    ]
}

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "id": 1,
    "status": "unrelated",
    "user_id": "13",
    "relation": {
        "redirect_uri": "http://www.evp.lt/123abc"
    },
    "accounts": [
        {
            "number": "EVP0123456789123",
            "order": 4
        }
    ]
}

Deleting card

Request

DELETE https://wallet.paysera.com/rest/v1/card/:id

Response

Response is an empty 204 response.

Example request

DELETE /rest/v1/card/1 HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="TaxLziPz2Jh7k/im0P6c1lp00a9moLBNk6YwUID7rJE="

Example response

HTTP/1.1 204 No Content

Retrieving card

Request

GET https://wallet.paysera.com/rest/v1/card/:id

Response

Response is a Card data structure.

Retrieving list of cards

List of cards can be retrieved by providing filter parameters.

Request

GET https://wallet.paysera.com/rest/v1/cards?user_id=:user_id&limit=:limit&offset=:offset

Parameters

user_id
required, ID of user that owns cards to fetch
limit
optional; maximum number of cards to be returned in one response. Defaults to 20, maximum available is 200
offset
optional; number of cards to skip. Defaults to 0

Response data structure

Parametras
Tipas
Pastabos
Aprašymas
cards
array of Card objects
always
Each item in array is Card object, see data structures
_metadata
object
always
Additional information about result

Depositing from card to account

To make deposit fom card to account, deposit must be created and then processed. Client must provide account to make deposit to and amount of money to charge from card. User must have account read access to deposit. Actual amount charged from user's payment card will increase because of commission.

Creating deposit

Request

POST https://wallet.paysera.com/rest/v1/card/:id/deposit

Request body structure

Parametras
Tipas
Pastabos
Aprašymas
account_number
string
required
Number of account to make deposit to
amount
Money object, see data structures
required
Amount to charge from card(commission is not included in this amount) and deposit to account

Response

Response is a Deposit data structure, see data structures.

Example request

POST /rest/v1/card/2/deposit HTTP/1.1
Host: wallet.paysera.com
Content-Type: application/json;charset=utf-8
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="KaDDR1TvbG/UFMsSzyInsER4scpInRTugZxJNeUvyIs=", ext="body_hash=ZBOAUM8szMr3v1xNr%2B%2FUII0Xw4PNQWzzI9BF03ySNFE%3D"
{
    "account_number": "EVP0123456789012",
    "amount": {
        "amount": 1313,
        "currency": "EUR"
    }
}

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "id": 26,
    "account_number": "EVP0123456789012",
    "amount": {
        "amount": 1313,
        "currency": "EUR",
        "amount_decimal": "13.13"
    },
    "commission": {
        "amount": 18,
        "currency": "EUR",
        "amount_decimal": "0.18"
    }
}

Processing deposit

To finalize the process of depositing from payment card to account, previously created deposit must be processed.

Request

PUT https://wallet.paysera.com/rest/v1/deposit/:id/process

Response

Response is a Deposit data structure, see data structures.

Example request

PUT /rest/v1/deposit/26/process HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="HEBVA0HNQnL7iKja1WXd7fC8tyRje8k88f56nDjD7Fo="

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "id": 26,
    "account_number": "EVP0123456789012",
    "amount": {
        "amount": 1313,
        "currency": "EUR",
        "amount_decimal": "13.13"
    },
    "commission": {
        "amount": 18,
        "currency": "EUR",
        "amount_decimal": "0.18"
    }
}

Data structures

Money data structure

Parametras
Tipas
Pastabos
Aprašymas
amount
float
always
Amount of money in cents
currency
string
always
Currency of money
amount_decimal
string
always
Decimal amount of money

Card data structure

Parametras
Tipas
Pastabos
Aprašymas
id
integer
always
ID of a card
user_id
integer
always
ID of an user, creating card
status
string
always
Current status of card. One of: unrelated, related, failed
related_at
integer
provided only if status is related
Date of card relation with Wallet API system in UNIX timestamp
relation
Relation object
provided only if status is unrelated
card_data
Card Data object
provided only if status is related
accounts
array of Card Account objects
always, may be empty
Links between card and accounts
commission_rule
Commission Rule object
provided only if status is related
Card charge commission information

Card Account data structure

Parametras
Tipas
Pastabos
Aprašymas
number
string
always
Number of account to link card to
order
integer
always
Card order (priority) number in relation with account

Card Data data structure

Parametras
Tipas
Pastabos
Aprašymas
number
string
always
Fragment of card number, for display purposes only
holder
string
always
Name on card, for display purposes only
type
string
always
Card type
country
string
if present
2-digit iso country code
expiration
Data structure, containing year and month parameters
if present
Card expiration date

Commission Rule data structure

Parametras
Tipas
Pastabos
Aprašymas
percent
float
Commission percentage
fix
integer
Fixed commission amount in cents
fix_decimal
string
Fixed commission decimal amount
min
integer
Provided only if percent provided
Min commission in cents
min_decimal
string
Provided only if percent provided
Min decimal commission
max
integer
Provided only if percent provided
Max commission in cents
max_decimal
string
Provided only if percent provided
Max decimal commission
currency
string
Provided only if fix, min or max provided
Commission currency

Relation data structure

Parametras
Tipas
Pastabos
Aprašymas
redirect_uri
string
always, read only
Uri that client should be redireted to
redirect_back_uri
string
optional, write only
Uri that client will be redirect to after card relation process is finished
locale
string
optional, write only
Locale in format of ISO 2-digit language code. Determines user interface language to use in card relation process. If not provided, user default locale is used.

Deposit data structure

Parametras
Tipas
Pastabos
Aprašymas
id
string
always
Id of a deposit
account_number
string
always
Number of account to make deposit to
amount
Money object
always
Amount to charge from card and deposit to account
commission
money object
always
Payment card charge commission