About managing payment cards

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 initialy created.

Request

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

Request body structure

Parameter Type Remarks Description
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 actualy editing links between cards and accounts. Client cannot edit any other card properties. Card editint is not allowed if it has status failed.

Request

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

Request body structure

Parameter Type Remarks Description
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

Parameter Type Remarks Description
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

Parameter Type Remarks Description
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"
    },
    "commission": {
        "amount": 18,
        "currency": "EUR"
    }
}

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"
    },
    "commission": {
        "amount": 18,
        "currency": "EUR"
    }
}

Data structures

Money data structure

Parameter Type Remarks Description
amount float always Amount of money in cents
currency string always Currency of money

Card data structure

Parameter Type Remarks Description
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

Parameter Type Remarks Description
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

Parameter Type Remarks Description
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

Parameter Type Remarks Description
percent float Commission percentage
fix integer Fixed commission amount in cents
min integer Provided only if percent provided Min commission in cents
max integer Provided only if percent provided Max commission in cents
currency string Provided only if fix, min or max provided Commission currency

Relation data structure

Parameter Type Remarks Description
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

Parameter Type Remarks Description
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