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 initially created.Request
POST https://wallet.paysera.com/rest/v1/card
Request body structure
user_id
accounts
relation
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 statusfailed
.
Request
PUT https://wallet.paysera.com/rest/v1/card/:id
Request body structure
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
_metadata
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
account_number
amount
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
amount
currency
amount_decimal
Card data structure
id
user_id
status
unrelated
, related
, failed
related_at
related
relation
unrelated
card_data
related
accounts
commission_rule
related
Card Account data structure
number
order
Card Data data structure
number
holder
type
country
expiration
year
and month
parameters
Commission Rule data structure
percent
fix
fix_decimal
min
percent
provided
min_decimal
percent
provided
max
percent
provided
max_decimal
percent
provided
currency
fix
, min
or max
provided
Relation data structure
redirect_uri
redirect_back_uri
locale
Deposit data structure
id
account_number
amount
commission