Cards

Cards can be issued to an account or can be non-personalized depending on program configuration. Each account can have a single active card. Card can be either virtual or plastic depending on the program. Cards can be used to pay in any physical location, online or withdraw money from ATMs. All virtual cards are activated upon issuing and can be used immediately. All plastic cards are not activated upon issuing and must be activated by the customer once received.

All virtual cards are activated upon issuing and can be used immediately.

All plastic cards are not activated upon issuing and must be activated by the customer once received.

Cards can be converted from virtual to plastic at a later stage. The PIN can be set on card creation or changed at a later stage on ATM.

Apple Pay/Google Pay push provision is supported depending on the program.

Card Creation

POST /v2/cards
Operation card_create

Request body

Field Type Description
program string (0,any)
account string (0,any)
merchant string (0,any) Required only for non pesonalized card in case must be assigned to merchant immediately.
user string (0,any) Required only for non pesonalized card in case must be assigned to user immediately.
aml string (0,any) Token of AML check. Conditinal: depending on program configuration
emboss_name string (0,any)
emboss_name_line4 string (0,any)
fulfil1 string (0,any)
fulfil2 string (0,any)
thermal_line1 string (0,any)
thermal_line2 string (0,any)
active boolean
pin string (0,any)
type string (0,any) required
plasticvirtual
first_name string (0,any)
last_name string (0,any)
alias string (0,any)
url string (0,any)

Example request

{
    "program": "card_eur",
    "account": "a451c34e-56d7-4e7f-8b6c-3322791ea792",
    "merchant": "b204ac3f-a23e-442b-a909-898238197070",
    "user": "b204ac3f-a23e-442b-a909-898238197070",
    "aml": "b204ac3f-a23e-442b-a909-898238197070",
    "emboss_name": "John Doe",
    "emboss_name_line4": "JohnDoe Ltd",
    "fulfil1": "123456",
    "fulfil2": "789123",
    "thermal_line1": "123456",
    "thermal_line2": "789123",
    "active": false,
    "pin": "1234",
    "type": "virtual",
    "first_name": "John",
    "last_name": "Doe",
    "alias": "Shopping Card",
    "delivery_details": {
        "city": "Sofia",
        "country": "BG",
        "county": "Sofia Grad",
        "zip": "1407",
        "address1": "James Bouchier 76A",
        "address2": "Paynetics Office",
        "address3": "Floor 2",
        "method": "string",
        "code": "string",
        "mobile_phone": "+3590000000"
    },
    "three_domain_enrolment": {
        "otp_sms": "+3590000000",
        "biometric": true
    },
    "url": "http://example.url"
}

Response

Field Type Description
code integer (0,any)

Example response

{
    "code": 0,
    "data": {
        "program": "account_eur",
        "token": "202f828a-c594-436d-b753-87c47556ef11",
        "merchant": "68f63588-2859-4997-8a23-29c59223e6ba",
        "user": "5eef34b5-69d8-4596-a9d3-b3aad500e825",
        "type": "default",
        "number": "0123456789",
        "link_key": "1234",
        "is_main": true,
        "status": "active",
        "multicurrency": false,
        "balances": [
            {
                "available": 1.23,
                "blocked": 1.23,
                "currency": "EUR",
                "token": "338e7368-4800-40ad-a4db-2e3df401087b",
                "iban": "BG31PATC4002115468108680",
                "sort_code": "123456",
                "account_number": "12345678",
                "number": "0123456789",
                "is_main": true
            }
        ]
    }
}

Card creation can require different fields depending on type (virtual, plastic) and affiliation (customer, non-personalized).

**Virtual Cards** - to create a virtual card associated with a customer account, please include the account identifier and type of card (virtual). In case the name of the merchant/user is not present in the customer profile, please specify them in the emboss name, emboss name line 4, first and last name (for natural persons) fields of the API request.

**Plastic Cards** - the requirements for plastic card issuing for an account associated with a customer are similar to those for virtual cards. The only addition is to include the delivery details of the cardholder.

The program associated with the account will be used when the card is created. Virtual accounts use the balance of the primary (main) account.

**Non-personalized virtual cards** - the required fields are program code and type of the card (virtual).

**Non-personalized plastic cards** - the requirements for non-personalized plastic card issuing are similar to those for non-personalized virtual cards. The only addition is to include the card delivery details.

For all cases above there are additional fields which can be provided like PIN, fulfil and thermal line data. Card 3DS details can also be provided in order for the card to be enrolled immediately after creation.

Please be advised that fulfil and thermal line data usage and placement on the card may vary depending on the personalization bureau. Contact your account manager before usage.

Card Conversion

PUT /v2/cards/{card}/convert
Operation card_convert

Path parameters

NameExampleDescription
card
string required
e61bac10-5be2-49e6-99e1-82ccfd4cb644 Token from card creation

Response

Field Type Description
code integer (0,any)

Example response

{
    "code": 0
}

Virtual cards can be converted to plastic. The requirement for conversion is card delivery details to be present when the virtual card was created or added when making a request to the conversion API endpoint.

Card Activation

PUT /v2/cards/{card}/activate
Operation card_activate

Path parameters

NameExampleDescription
card
string required
e61bac10-5be2-49e6-99e1-82ccfd4cb644 Token from card creation

Request body

Field Type Description
aml string (0,any) Conditional: For some cases for non personalized cards.

Example request

{
    "aml": "f37377c0-50c0-4324-a330-902f92db23a4"
}

Response

Field Type Description
code integer (0,any)

Example response

{
    "code": 0
}

Plastic cards are always created not activated, meaning no transactions can be executed with the card before activation. Activation is a one-time process and must be done once the card is received by the cardholder for security reasons.

Card Renewal

PUT /v2/cards/{card}/renew
Operation card_renew

Path parameters

NameExampleDescription
card
string required
—

Request body

Field Type Description
mode integer (0,any) required
expiry_date string (0,any)

Example request

{
    "mode": "integer",
    "expiry_date": "string"
}

Response

Field Type Description
code integer (0,any)

Example response

{
    "code": 0,
    "data": {
        "token": "d0788c1e-59b7-4b6e-bbe1-f6e9fc09be58",
        "external_identifier": "473854628"
    }
}

Card Status and Termination

There are 3 statuses that a card can have:

Active

By default, cards are created in active status. This means that card transactions can be executed with the card on POS, ATM, E-commerce, etc. 

Please be advised, active status is different than card activation. While activation is a one-time process, card statuses can be changed between active/inactive at any time.

Inactive

Inactive status restricts all transactions with the card. The status is reversable to active.

Closed

Void status destroys the card. No transactions can be done.

! The status is not reversable !

{ PUT }

PUT /v2/cards/{card}/status
Operation card_status

Path parameters

NameExampleDescription
card
string required
e61bac10-5be2-49e6-99e1-82ccfd4cb644 Token from card creation

Request body

Field Type Description
status string (0,any) required
activeinactive

Example request

{
    "status": "string"
}

Response

Field Type Description
code integer (0,any)

Example response

{
    "code": 0
}

{ DELETE }

DELETE /v2/cards/{card}
Operation card_terminate

Path parameters

NameExampleDescription
card
string required
e61bac10-5be2-49e6-99e1-82ccfd4cb644 Token from card creation

Response

Field Type Description
code integer (0,any)

Example response

{
    "code": 0
}

Card Limits and Fees

PUT /v2/cards/{card}/groups
Operation card_groups

Path parameters

NameExampleDescription
card
string required
e61bac10-5be2-49e6-99e1-82ccfd4cb644 Token from card creation

Request body

Field Type Description
usage string (0,any)
fees string (0,any)
schedule_fees string (0,any)
web_service_fees string (0,any)
limits string (0,any)
linkage string (0,any)
mcc string (0,any)
whitelist string (0,any)

Example request

{
    "usage": "usage_group_1",
    "fees": "fee_group_1",
    "schedule_fees": "schedule_fee_group_1",
    "web_service_fees": "web_services_fee_group_1",
    "limits": "limits_group_1",
    "linkage": "linkage_group_1",
    "mcc": "mcc_black_group_1",
    "whitelist": "whitelist_group_1"
}

Response

Field Type Description
code integer (0,any)

Example response

{
    "code": 0
}

By default, limit and fee groups are set upon card creation depending on program configuration. Each limit/fee group can be changed or removed at any time.

The group codes will be provided by Paynetics and must be associated with the program, or the change will not be executed.

Card PIN Management

Card PIN can be retrieved using API at any time.

{ GET }

GET /v2/cards/{card}/pin
Operation card_retrieve_pin

Path parameters

NameExampleDescription
card
string required
e61bac10-5be2-49e6-99e1-82ccfd4cb644 Token from card creation

Response

Field Type Description
code integer (0,any)

Example response

{
    "code": 0,
    "data": {
        "pin": "0123"
    }
}

{ POST }

POST /v2/cards/{card}/pin/send
Operation card_send_pin

Path parameters

NameExampleDescription
card
string required
e61bac10-5be2-49e6-99e1-82ccfd4cb644 Token from card creation

Response

Field Type Description
code integer (0,any)

Example response

{
    "code": 0
}

It can be sent to the cardholder via SMS depending on the program configuration. The mobile phone number added upon card creation will be used. In case the phone number must be changed please use the cardholder details update API.

{ DELETE }

DELETE /v2/cards/{card}/pin/reset
Operation card_reset_pin

Path parameters

NameExampleDescription
card
string required
e61bac10-5be2-49e6-99e1-82ccfd4cb644 Token from card creation

Response

Field Type Description
code integer (0,any)

Example response

{
    "code": 0
}

Error counter can be reset using API. This is needed in case the cardholder has entered an incorrect PIN/CVV several times on POS, ATM or online.

Card 3DS Enrollment

POST /v2/cards/{card}/3ds
Operation card_3ds_enrol

Path parameters

NameExampleDescription
card
string required
e61bac10-5be2-49e6-99e1-82ccfd4cb644 Token from card creation

Request body

Field Type Description
otp_sms string (0,any) required
biometric boolean

Example request

{
    "otp_sms": "+3590000000",
    "biometric": true
}

Response

Field Type Description
code integer (0,any)

Example response

{
    "code": 0
}

Card can be enrolled for 3DS for both OTP SMS authentication and/or biometric authentication. For OTP SMS authentication the mobile phone number of the account holder is required.

Enrolment mobile phone

PUT /v2/cards/{card}/3ds
Operation card_3ds_update

Path parameters

NameExampleDescription
card
string required
e61bac10-5be2-49e6-99e1-82ccfd4cb644 Token from card creation

Request body

Field Type Description
otp_sms string (0,any) required

Example request

{
    "otp_sms": "+3590000000"
}

Response

Field Type Description
code integer (0,any)

Example response

{
    "code": 0
}

**\* number can be amended at a later stage.**

Enrolment for both types

DELETE /v2/cards/{card}/3ds
Operation card_3ds_remove

Path parameters

NameExampleDescription
card
string required
e61bac10-5be2-49e6-99e1-82ccfd4cb644 Token from card creation

Request body

Field Type Description
type string (0,any)

Example request

{
    "type": "string"
}

Response

Field Type Description
code integer (0,any)

Example response

{
    "code": 0
}

**\* can be disabled at any time but is not recommended.**

List / detail

Something about list and detail

List

GET /v2/cards/{page}/{limit}
Operation cards_list

Path parameters

NameExampleDescription
page
string required
—
limit
string required
—

Query parameters

NameExampleDescription
merchant
string
{{uuid}} Token of merchant
user
string
{{uuid}} Token of user

Response

Field Type Description
code integer (0,any)

Example response

{
    "code": 0,
    "data": {
        "items": [
            {
                "token": "string",
                "type": "string",
                "is_digitalized": "boolean",
                "is_activated": "boolean",
                "is_otp_sms_enabled": "boolean",
                "is_bio_enabled": "boolean",
                "external_identifier": "string",
                "status": "string",
                "branch_code": "string",
                "delivery_details": {
                    "country": "string",
                    "county": "string",
                    "city": "string",
                    "zip": "string",
                    "address1": "string",
                    "address2": "string",
                    "address3": "string",
                    "mobile_phone": "string",
                    "first_name": "string",
                    "last_name": "string"
                },
                "is_issued": "boolean",
                "user": "string",
                "merchant": "string",
                "first_name": "string",
                "last_name": "string",
                "emboss_name": "string",
                "emboss_name_line4": "string"
            }
        ],
        "total_items": "1"
    }
}

Detail

GET /v2/cards/{card}
Operation card_details

Path parameters

NameExampleDescription
card
string required
e61bac10-5be2-49e6-99e1-82ccfd4cb644 Token from card creation
card
string required
e61bac10-5be2-49e6-99e1-82ccfd4cb644 Token from card creation

Response

Field Type Description
code integer (0,any)

Example response

{
    "code": 0,
    "data": {
        "token": "string",
        "type": "string",
        "is_digitalized": "boolean",
        "is_activated": "boolean",
        "is_otp_sms_enabled": "boolean",
        "is_bio_enabled": "boolean",
        "external_identifier": "string",
        "status": "string",
        "branch_code": "string",
        "delivery_details": {
            "country": "string",
            "county": "string",
            "city": "string",
            "zip": "string",
            "address1": "string",
            "address2": "string",
            "address3": "string",
            "mobile_phone": "string",
            "first_name": "string",
            "last_name": "string"
        },
        "is_issued": "boolean",
        "user": "string",
        "merchant": "string",
        "first_name": "string",
        "last_name": "string",
        "emboss_name": "string",
        "emboss_name_line4": "string"
    }
}

Number & CVV

Card Number

Firs half

GET /v2/cards/{card}/first-half
Operation card_number

Path parameters

NameExampleDescription
card
string required
e61bac10-5be2-49e6-99e1-82ccfd4cb644 Token from card creation

Response

Field Type Description
code integer (0,any)

Example response

{
    "code": 0,
    "data": {
        "pan": "5355XXXXXXXX0316",
        "expiration_month": "04",
        "expiration_year": "26"
    }
}

Second half

GET /v2/cards/{card}/second-half
Operation card_number

Path parameters

NameExampleDescription
card
string required
e61bac10-5be2-49e6-99e1-82ccfd4cb644 Token from card creation

Response

Field Type Description
code integer (0,any)

Example response

{
    "code": 0,
    "data": {
        "pan": "XXXX94203030XXXX",
        "cvv": "671"
    }
}

Card Provisioning

Apple/Google wallet push provisioning is supported depending on the program. Push provisioning is used for automatic In-App provisioning for both platforms.

The API request will return an encrypted payload required for the card to be added to Apple/Google Wallet using the platform SDK/API.

Apple Wallet push provisioning

POST /v2/cards/{card}/push-provisioning/apple
Operation push_provisioning_apple_card

Path parameters

NameExampleDescription
card
string required
e61bac10-5be2-49e6-99e1-82ccfd4cb644 Token from card creation

Request body

Field Type Description
nonce_signature string (0,any) required
certificates array (0,any) required
nonce string (0,any) required

Example request

{
    "nonce_signature": "ZXhhbXBsZQo=",
    "certificates": [],
    "nonce": "ZXhhbXBsZQo="
}

Response

Field Type Description
code integer (0,any)

Example response

{
    "code": 0
}

Google Wallet push provisioning

POST /v2/cards/{card}/push-provisioning/google
Operation push_provisioning_google_card

Path parameters

NameExampleDescription
card
string required
e61bac10-5be2-49e6-99e1-82ccfd4cb644 Token from card creation

Request body

Field Type Description
stable_hardware_id string (0,any) required
active_wallet_id string (0,any) required

Example request

{
    "stable_hardware_id": "ZXhhbXBsZQo=",
    "active_wallet_id": "ZXhhbXBsZQo="
}

Response

Field Type Description
code integer (0,any)

Example response

{
    "code": 0
}

Apple Wallet encrypted payload

POST /v2/cards/{card}/apple/encrypt
Operation enc_card

Path parameters

NameExampleDescription
card
string required
e61bac10-5be2-49e6-99e1-82ccfd4cb644 Token from card creation

Request body

Field Type Description
nonce_signature string (0,any)
certificates array (0,any)
nonce string (0,any)

Example request

{
    "nonce_signature": "string",
    "certificates": [
        "string"
    ],
    "nonce": "string"
}

Response

Field Type Description
code integer (0,any)

Example response

{
    "code": 0,
    "data": {
        "encryption_pass_data": "string",
        "activation_data": "string",
        "ephemeral_public_key": "string"
    }
}

Google Wallet encrypted payload

POST /v2/cards/{card}/google/encrypt
Operation enc_card

Path parameters

NameExampleDescription
card
string required
e61bac10-5be2-49e6-99e1-82ccfd4cb644 Token from card creation

Request body

Field Type Description
stable_hardware_id string (0,any)
active_wallet_id string (0,any)

Example request

{
    "stable_hardware_id": "string",
    "active_wallet_id": "string"
}

Response

Field Type Description
code integer (0,any)

Example response

{
    "code": 0,
    "data": {
        "opc": 0,
        "address": {
            "card_type": "string",
            "real_name": "string"
        }
    }
}

Payment tokens

GET /v2/cards/{card}/payment-tokens
Operation card_tokens

Path parameters

NameExampleDescription
card
string required
e61bac10-5be2-49e6-99e1-82ccfd4cb644 Token from card creation or external identifier

Response

Field Type Description
code integer (0,any)

Example response

{
    "code": 0,
    "data": {
        "payment_tokens": [
            {
                "payment_token_id": "string",
                "status": "string",
                "tokenised_status": "integer",
                "digitisation_ref": "string",
                "device_id": "string"
            }
        ]
    }
}

Change payment token

POST /v2/cards/{card}/payment-tokens/change
Operation card_tokens

Path parameters

NameExampleDescription
card
string required
e61bac10-5be2-49e6-99e1-82ccfd4cb644 Token from card creation or external identifier

Request body

Field Type Description
payment_token_id string (0,any) required
activate integer (0,any) required
status string (0,any)

Example request

{
    "payment_token_id": "string",
    "activate": "integer",
    "status": "string"
}

Response

Field Type Description
payment_token_id string (0,any)
action_code string (0,any)

Example response

{
    "payment_token_id": "token123",
    "action_code": "00"
}

Device tokens

GET /v2/cards/{card}/tokens/{deviceId}
Operation card_tokens

Path parameters

NameExampleDescription
card
string required
e61bac10-5be2-49e6-99e1-82ccfd4cb644 Token from card creation
deviceId
string required
all Device ID

Response

Field Type Description
code integer (0,any)

Example response

{
    "code": 0,
    "data": {
        "card_tokens": "string"
    }
}

esc
↑↓ navigate ↵ open esc close
Copied