Skip to main content
API docs by Redocly

Paynovus CIP Partner API (1.0.0)

Download OpenAPI specification:Download

Paynovus Development Team: office@paynovus.com

The CIP Partner API exposes a JWT-authenticated surface for trusted partners to manage B2B tenants they own, onboard cardholders under those tenants, operate individual accounts they onboard directly, create and operate cards under any of those accounts, and query fees / delivery options.

All endpoints are mounted under /api/partner and require an ES512 Bearer JWT whose iss matches the partner's registered URL and whose sub equals the partner's _id.

Authentication

  1. Generate a P-521 (secp521r1) ES512 keypair and provide the public key to Paynovus — it is stored on the Partner record.

  2. Sign a JWT with the partner's private key. The token must contain:

    {
  "iss": "https://your-registered-url.com",
  "sub": "<partnerObjectId>",
  "exp": <unix-seconds, +1 minute>,
  "iat": <unix-seconds>
}

  3. Send the token on every request:

    Authorization: Bearer <jwt>

Partners are pre-trusted: a successful JWT verification pass grants full access to every resource owned by the calling partner. No additional role or permission checks are required from the caller.

All endpoints automatically scope their results to the calling partner — if you pass an :id that does not belong to your partner, the endpoint returns 404 Not Found with no further detail, regardless of whether the resource exists in another partner's scope.

Partner API

Endpoints that target the authenticated partner itself (/health-check, /me). Useful for connectivity checks and self-introspection.

Health check

Public liveness probe. Does not require authentication — useful for partner integration connectivity checks and infrastructure readiness probes. Always returns 200 OK with the body OK.

Responses

Response Schema: text/plain
string

Get partner identity

Returns the authenticated partner profile along with every B2B tenant and individual onboarding owned by that partner.

The b2bAccounts and individuals arrays are returned in full. This endpoint does not paginate and does not return a separate count field for either array; use the array lengths when counts are needed.

The response always reflects exactly the authenticated partner.

Authorizations:
JWTBearerAuth

Responses

Response Schema: application/json
object (Partner)
activeTenantId
string or null

The B2B tenant this request was scoped to (null when the partner has no B2B tenant — common for individual-only partners).

Array of objects (B2BTenant)
Array of objects (IndividualAccountSummary)

Response samples

Content type
application/json
{
  • "partner": {
    },
  • "activeTenantId": "string",
  • "b2bAccounts": [
    ],
  • "individuals": [
    ]
}

Business Accounts (B2B)

Partner-owned B2B tenants and the cardholders that live under them. Tenants are created by PayNovus on the partner's behalf — partners can list, fetch, and operate on tenants they're already linked to. Cardholder creation under a tenant is partner-driven and goes through a PayNovus approval task (returned as PENDING).

List B2B tenants

Returns every B2B tenant linked to your partner. The endpoint is full-list: it does not paginate and the entire array is returned in a single response with a count field.

The response is intentionally minimal — only the fields a partner needs to render a tenant-picker UI. Pull the full tenant details (IBANs, products, status, contacts) via GET /business/accounts/{b2bAccountId}.

Authorizations:
JWTBearerAuth

Responses

Response Schema: application/json
count
required
integer
required
Array of objects (PartnerB2BAccountListItem)

Response samples

Content type
application/json
{
  • "count": 0,
  • "data": [
    ]
}

Get B2B tenant details

Returns the tenant document plus the linked debit-account rows it owns. If the :b2bAccountId does not belong to your partner, the response is 404 Not Found — identical whether the tenant does not exist or belongs to another partner (no enumeration).

Authorizations:
JWTBearerAuth
path Parameters
b2bAccountId
required
string

B2B tenant identifier — must be owned by the calling partner.

Responses

Response Schema: application/json
success
boolean
object (B2BTenant)
object (DebitAccount)

A debit account (IBAN) linked to a tenant or cardholder. accountNumber is the IBAN.

Array of objects (DebitAccount)

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "debitAccount": {
    },
  • "debitAccounts": [
    ]
}

Get live balances for every IBAN linked to the tenant

Returns the live availableBalance for each IBAN linked to the tenant.

Per-IBAN failure handling. Any IBAN whose balance cannot be resolved is surfaced in the response with status: "error" and an errorMessage field — failures are never silently reported as zero. The overall HTTP status remains 200 so a partner UI can still render the IBANs that succeeded.

Authorizations:
JWTBearerAuth
path Parameters
b2bAccountId
required
string

B2B tenant identifier — must be owned by the calling partner.

Responses

Response Schema: application/json
success
boolean
count
integer
Array of objects (BalanceEntry)

Response samples

Content type
application/json
{
  • "success": true,
  • "count": 0,
  • "data": [
    ]
}

List IBANs eligible for new card issuance

Returns the tenant's debit accounts that are eligible for issuing a new card. Mirrors the same eligibility filter the Dashboard uses (active status, primary currency resolved).

The returned shape mirrors Account; pass any of these IBANs to a card-creation endpoint's accNo parameter.

Authorizations:
JWTBearerAuth
path Parameters
b2bAccountId
required
string

B2B tenant identifier — must be owned by the calling partner.

Responses

Response Schema: application/json
success
boolean
count
integer
Array of objects (B2BIssuableIbanAccount)

Response samples

Content type
application/json
{
  • "success": true,
  • "count": 0,
  • "accounts": [
    ]
}

Submit IBAN settings for PayNovus approval

Submits a settings change (name, isActive, isPrimary) for an existing linked IBAN. Like the admin-side equivalent, the change goes through an approval task: the partner gets back a taskId/status: PENDING and PayNovus applies the change once it is approved.

At least one of name, isActive, or isPrimary must be supplied. isPrimary only accepts true (a tenant must always have one primary account — the way to move the primary is to set a different IBAN, not to clear the current one).

Authorizations:
JWTBearerAuth
path Parameters
b2bAccountId
required
string

B2B tenant identifier — must be owned by the calling partner.

header Parameters
Idempotency-Key
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

Optional idempotency key to ensure safe retries for non-GET requests.

When provided, the API remembers your request and returns the exact same result if the same key is sent within 60 seconds. This protects against duplicate operations in case of network timeouts or accidental retries.

Recommended: Use a UUID v4 for each logical operation.

Response headers:

  • Same key + same request → original response + X-Idempotency-Replay: true
  • Same key + different request → 409 Conflict
  • Request still processing → 202 Accepted
Request Body schema: application/json
required
IBAN
required
string = 22 characters

IBAN whose settings are being changed. Exactly 22 characters.

name
string <= 100 characters

Optional display label; pass empty string to clear.

isActive
boolean

When false, the IBAN is hidden from new-card issuance. Already issued cards keep using it.

isPrimary
boolean
Value: true

Only true is accepted. To move the primary, set a different IBAN's isPrimary: true.

Responses

Request samples

Content type
application/json
{
  • "IBAN": "BG44TRUD40059780005961",
  • "name": "Payroll Account",
  • "isActive": true,
  • "isPrimary": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "b2bAccountId": "string",
  • "taskId": "string",
  • "status": "PENDING"
}

List products assigned to a B2B tenant

Returns the ProductVersion documents linked to the tenant. Without the kind query parameter the endpoint returns every product.

Each product carries its own per-product card-limit envelopes under limits (e.g. ATM_CCA_LMT, POS_PUR_LMT). The limits field is omitted on products that have no configured envelopes.

Authorizations:
JWTBearerAuth
path Parameters
b2bAccountId
required
string

B2B tenant identifier — must be owned by the calling partner.

query Parameters
kind
string
Enum: "virtual" "physical"

Optional filter — when set to virtual or physical, the endpoint narrows the returned ProductVersion list to the card type the partner plans to issue.

Responses

Response Schema: application/json
success
boolean
Array of objects (ProductVersion)

Response samples

Content type
application/json
{
  • "success": true,
  • "products": [
    ]
}

List audit logs for a B2B tenant

Paginated audit log for the tenant. Defaults: page=1, limit=50. No hard server-side cap on limit.

Filters can be combined: ?action=LOCK_CARD&result=SUCCESS&from=2025-01-01. Tenant ownership is verified against the calling partner; foreign tenants return 404.

Authorizations:
JWTBearerAuth
path Parameters
b2bAccountId
required
string

B2B tenant identifier — must be owned by the calling partner.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number for pagination. Starts at 1. Default values depend on the endpoint: transactions default to 1, and audit/status-history endpoints default to 1.

limit
integer >= 1
Default: 50
Example: limit=50

Number of audit-log or card-status-history records to return per page. Defaults to 50. There is currently no enforced maximum limit value in the Partner API implementation. Pass a larger value directly, for example ?page=1&limit=3000.

from
string <date-time>

Inclusive lower bound on the entry's createdAt (ISO 8601, e.g. 2025-01-01 or 2025-01-01T00:00:00Z). Invalid values yield 400 Bad Request.

to
string <date-time>

Inclusive upper bound on the entry's createdAt (ISO 8601, e.g. 2025-12-31 or 2025-12-31T23:59:59Z). Invalid values yield 400 Bad Request.

sort
string

Sort order, comma-separated field:direction pairs (use - for descending). Defaults to -createdAt when omitted. Example: ?sort=-createdAt.

cardId
string

Filter by card cardKey. The alias card is also accepted.

customerId
string

Filter by cardholder clientCode (e.g. RYVL-9287). The alias clientId is also accepted.

action
string

Filter by action name (e.g. CREATE_VIRTUAL_CARD).

result
string
Enum: "SUCCESS" "FAILED"

Filter by outcome.

Responses

Response Schema: application/json
success
boolean
Array of objects (AuditLogEntry)
object (Pagination)

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "pagination": {
    }
}

List card-status history for a B2B tenant

Paginated card-status history across every card issued under the tenant. Defaults: page=1, limit=50. No hard server-side cap on limit.

Filters can be combined: ?fromStatus=ACTIVE&toStatus=LOCKED&triggeredBy=PARTNER.

Authorizations:
JWTBearerAuth
path Parameters
b2bAccountId
required
string

B2B tenant identifier — must be owned by the calling partner.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number for pagination. Starts at 1. Default values depend on the endpoint: transactions default to 1, and audit/status-history endpoints default to 1.

limit
integer >= 1
Default: 50
Example: limit=50

Number of audit-log or card-status-history records to return per page. Defaults to 50. There is currently no enforced maximum limit value in the Partner API implementation. Pass a larger value directly, for example ?page=1&limit=3000.

from
string <date-time>

Inclusive lower bound on the entry's createdAt (ISO 8601, e.g. 2025-01-01 or 2025-01-01T00:00:00Z). Invalid values yield 400 Bad Request.

to
string <date-time>

Inclusive upper bound on the entry's createdAt (ISO 8601, e.g. 2025-12-31 or 2025-12-31T23:59:59Z). Invalid values yield 400 Bad Request.

sort
string

Sort order, comma-separated field:direction pairs (use - for descending). Defaults to -createdAt when omitted. Example: ?sort=-createdAt.

cardId
string

Filter by card cardKey. The alias card is also accepted.

fromStatus
string

Filter by the card status before the change. Accepts either the status name (e.g. ACTIVE) or the raw status code (e.g. WW).

toStatus
string

Filter by the card status after the change. Accepts either the status name (e.g. LOCKED) or the raw status code (e.g. WL).

triggeredBy
string
Enum: "PARTNER" "USER" "SYSTEM"

Filter by who drove the status change.

triggeredByUserId
string

Filter by the dashboard user that drove the change (only set when triggeredBy=USER). Pass a User ObjectId.

Responses

Response Schema: application/json
success
boolean
Array of objects (CardStatusHistoryEntry)
object (Pagination)

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "pagination": {
    }
}

List transactions for a B2B tenant

Paginated transactions for the tenant. Defaults: page=1, limit=10. No hard server-side cap on limit.

Authorizations:
JWTBearerAuth
path Parameters
b2bAccountId
required
string

B2B tenant identifier — must be owned by the calling partner.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number for pagination. Starts at 1. Default values depend on the endpoint: transactions default to 1, and audit/status-history endpoints default to 1.

limit
integer >= 1
Default: 10
Example: limit=10

Number of transactions to return per page. Defaults to 10. There is currently no enforced maximum limit value in the Partner API implementation. Pass a larger value directly, for example ?page=1&limit=3000, unless the upstream provider rejects it.

Responses

Response Schema: application/json
Array of objects (Transaction)
object

Response samples

Content type
application/json
{
  • "transactions": [
    ],
  • "pagination": {
    }
}

List all cardholders owned by the partner

Returns every cardholder owned by the calling partner across all linked B2B tenants and direct partner-owned individual onboardings. Unlike /business/accounts/{b2bAccountId}/cardholders (tenant-scoped), this endpoint is partner-wide.

The list includes B2B self-admin records (a tenant manager who is also a cardholder) — those still belong to the partner.

Full-list response — no pagination. The response includes the tenant snapshot (companyName, clientCode, status) for the b2bClient of each cardholder when populated.

Authorizations:
JWTBearerAuth

Responses

Response Schema: application/json
success
boolean
count
integer
Array of objects (IndividualOnboardingRecord)

Response samples

Content type
application/json
{
  • "success": true,
  • "count": 0,
  • "data": [
    ]
}

List cardholders under a B2B tenant

Lists every IndividualOnboarding record whose b2bClient matches the tenant. The list excludes self-admin rows (isSelfAdmin !== true) so it returns end-user cardholders, not the tenant-manager themselves.

Full-list response — no pagination. The response is the full onboarding document.

Authorizations:
JWTBearerAuth
path Parameters
b2bAccountId
required
string

B2B tenant identifier — must be owned by the calling partner.

Responses

Response Schema: application/json
success
boolean
count
integer
Array of objects (IndividualOnboardingRecord)

Response samples

Content type
application/json
{
  • "success": true,
  • "count": 0,
  • "data": [
    ]
}

Create a B2B cardholder

Submits a new B2B cardholder for PayNovus approval. The resulting onboarding starts in applicationStatus: PENDING; a taskId is returned so the partner can poll for the approval outcome.

You are not asked to provide a Dashboard user — there is no password to set for the cardholder on this surface. If the supplied email is already in use under the same tenant, the endpoint rejects the request with 409 Conflict before the onboarding is created.

Authorizations:
JWTBearerAuth
path Parameters
b2bAccountId
required
string

B2B tenant identifier — must be owned by the calling partner.

header Parameters
Idempotency-Key
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

Optional idempotency key to ensure safe retries for non-GET requests.

When provided, the API remembers your request and returns the exact same result if the same key is sent within 60 seconds. This protects against duplicate operations in case of network timeouts or accidental retries.

Recommended: Use a UUID v4 for each logical operation.

Response headers:

  • Same key + same request → original response + X-Idempotency-Replay: true
  • Same key + different request → 409 Conflict
  • Request still processing → 202 Accepted
Request Body schema: application/json
required
required
object
required
object
required
object
required
object
citizenship
required
string <= 40 characters

ISO 3166-1 alpha-2 country code.

embossedName1
required
string

Primary line printed on the card.

embossedName2
required
string

Secondary line printed on the card (often the company name).

firmOccupation
required
string <= 40 characters
hasCompletedBiometrics
required
boolean
isPep
required
boolean
pepUnderstanding
string
Enum: "yes_i_do" "need_more_info"

Required when isPep is true.

pepAcknowledgement
boolean

Required when isPep is true.

hasAgreedToTerms
boolean
hasAgreedToTariffs
boolean
hasAgreedToCardholderLimitation
boolean
hasAgreedToNoThirdPartyCards
boolean
hasAgreedToCompanyLiability
boolean
uboPepStatement
object

Required when isPep is true. See individual onboarding schema.

Responses

Request samples

Content type
application/json
{
  • "personalInfo": {
    },
  • "address": {
    },
  • "idDocument": {
    },
  • "taxInfo": {
    },
  • "citizenship": "string",
  • "embossedName1": "string",
  • "embossedName2": "string",
  • "firmOccupation": "string",
  • "hasCompletedBiometrics": true,
  • "isPep": true,
  • "pepUnderstanding": "yes_i_do",
  • "pepAcknowledgement": true,
  • "hasAgreedToTerms": true,
  • "hasAgreedToTariffs": true,
  • "hasAgreedToCardholderLimitation": true,
  • "hasAgreedToNoThirdPartyCards": true,
  • "hasAgreedToCompanyLiability": true,
  • "uboPepStatement": { }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "cardholderId": "string",
  • "taskId": "string",
  • "status": "PENDING"
}

Get a B2B cardholder

Returns the full IndividualOnboarding document plus the resolved debit accounts (accounts), the active cards (cards), and the live balances (balance). Same precedence as the cardholder-side endpoints.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Cardholder identifier (the IndividualOnboarding record id). Must resolve to a cardholder whose b2bClient is owned by the calling partner; foreign cardholders return 404 without enumeration.

Responses

Response Schema: application/json
success
boolean
object (IndividualOnboardingRecord)

A cardholder onboarding record.

Array of objects (DebitAccount)
Array of objects (AccountCard)
balance
number

Live availableBalance for the first resolved debit account. Returns 0 when no accounts resolve or the upstream call fails.

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "accounts": [
    ],
  • "cards": [
    ],
  • "balance": 0
}

List cards for a B2B cardholder

Returns every active card (AccountCard) under the cardholder. Full-list response — no pagination.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Cardholder _id — must resolve to a cardholder owned by the calling partner.

Responses

Response Schema: application/json
success
boolean
count
integer
Array of objects (AccountCard)

Response samples

Content type
application/json
{
  • "success": true,
  • "count": 0,
  • "data": [
    ]
}

List IBANs eligible for issuing against a B2B cardholder

Resolves the IBANs the cardholder is allowed to issue against — the cardholder's own debit accounts plus any B2B-shared tenant accounts (if the cardholder is reusing company accounts).

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Cardholder _id — must resolve to a cardholder owned by the calling partner.

Responses

Response Schema: application/json
success
boolean
count
integer
Array of objects (B2BIssuableIbanAccount)

Response samples

Content type
application/json
{
  • "success": true,
  • "count": 0,
  • "accounts": [
    ]
}

Issue a virtual card for a B2B cardholder

Issues a virtual card. The only required body field is productCode — pick from the tenant's products via GET /business/accounts/{b2bAccountId}/products. Pass accNo to override which IBAN funds the card; otherwise the cardholder's first eligible IBAN is used. Embossed-name fields and currency default from the cardholder record.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Cardholder _id — must resolve to a cardholder owned by the calling partner.

header Parameters
Idempotency-Key
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

Optional idempotency key to ensure safe retries for non-GET requests.

When provided, the API remembers your request and returns the exact same result if the same key is sent within 60 seconds. This protects against duplicate operations in case of network timeouts or accidental retries.

Recommended: Use a UUID v4 for each logical operation.

Response headers:

  • Same key + same request → original response + X-Idempotency-Replay: true
  • Same key + different request → 409 Conflict
  • Request still processing → 202 Accepted
Request Body schema: application/json
required
productCode
required
string

Product code of one of the tenant's products (GET /business/accounts/{b2bAccountId}/products).

accNo
string

Optional IBAN to draw funding from. If omitted, the cardholder's first eligible IBAN is used. Use GET /business/cardholders/{id}/ibans/for-issuing to enumerate options.

Responses

Response Schema: application/json
success
required
boolean
message
required
string
required
object (PartnerVirtualIssuedCard)

Slim card shape returned by the partner-individual virtual-card creation endpoint (POST /api/partner/individual/accounts/{id}/cards/virtual).

The card-issuing platform's virtual-card creation response carries only these. Lifecycle / shipping fields (set_pin, set_password, deliveryMethod, deliveryAddress, isAdminBlocked, _id, createdAt, updatedAt, __v) are omitted on the virtual path — call GET /api/partner/cards/{id} for the full record.

Request samples

Content type
application/json
{
  • "productCode": "R004",
  • "accNo": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Virtual card created successfully",
  • "data": {
    }
}

Issue a physical card for a B2B cardholder

Issues a physical card against one of the cardholder's eligible IBANs. deliveryMethod is required (use GET /fees/delivery-methods to discover the available _ids). phoneNumber and country are required for the delivery address; embossName1 overrides the cardholder default.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Cardholder _id — must resolve to a cardholder owned by the calling partner.

header Parameters
Idempotency-Key
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

Optional idempotency key to ensure safe retries for non-GET requests.

When provided, the API remembers your request and returns the exact same result if the same key is sent within 60 seconds. This protects against duplicate operations in case of network timeouts or accidental retries.

Recommended: Use a UUID v4 for each logical operation.

Response headers:

  • Same key + same request → original response + X-Idempotency-Replay: true
  • Same key + different request → 409 Conflict
  • Request still processing → 202 Accepted
Request Body schema: application/json
required
productCode
required
string
required
object

Delivery method chosen from GET /fees/delivery-methods?country=….

phoneNumber
string

Delivery contact phone.

country
string

ISO 3166-1 alpha-3 country code for the delivery address.

embossName1
string

Optional override for the card's primary embossed name.

Responses

Response Schema: application/json
success
required
boolean
message
required
string
required
object (PartnerPhysicalIssuedCard)

Full card shape returned by the partner-individual physical-card creation endpoint (POST /api/partner/individual/accounts/{id}/cards/physical).

Mirrors the full AccountCard document with all lifecycle and shipping fields populated. See AccountCard for the canonical field-by-field description.

Request samples

Content type
application/json
{
  • "productCode": "R003",
  • "deliveryMethod": {
    },
  • "phoneNumber": "string",
  • "country": "BGR",
  • "embossName1": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Physical card created successfully",
  • "data": {
    }
}

Request a prepaid virtual card for a B2B cardholder

Requests a prepaid virtual card. The card is not created in this call. The call checks the request and answers 200 with status: "PENDING". The card is created in the background, usually within 2-3 minutes, and then appears in the card list of the cardholder.

The body is optional. productCode can only be R008 (the default), and the currency is EUR.

A request that is not valid (for example a product that is not assigned to the company) is refused with 400 before anything is requested.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Cardholder _id — must resolve to a cardholder owned by the calling partner.

header Parameters
Idempotency-Key
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

Optional idempotency key to ensure safe retries for non-GET requests.

When provided, the API remembers your request and returns the exact same result if the same key is sent within 60 seconds. This protects against duplicate operations in case of network timeouts or accidental retries.

Recommended: Use a UUID v4 for each logical operation.

Response headers:

  • Same key + same request → original response + X-Idempotency-Replay: true
  • Same key + different request → 409 Conflict
  • Request still processing → 202 Accepted
Request Body schema: application/json
optional
productCode
string
Default: "R008"
Value: "R008"

The prepaid virtual card product. Only R008 is accepted.

currencyCode
string
Default: "EUR"
Value: "EUR"

Currency of the card. Only EUR is accepted.

nickname
string

Optional card nickname.

Responses

Response Schema: application/json
message
string
object

Request samples

Content type
application/json
{
  • "nickname": "Online shopping"
}

Response samples

Content type
application/json
{
  • "message": "Prepaid physical card requested. The card will be created in a few minutes (2-3 minutes).",
  • "data": {
    }
}

Request a prepaid physical card for a B2B cardholder

Requests a prepaid physical card. The card is not created in this call. The call checks the request and answers 200 with status: "PENDING". The card is created in the background, usually within 2-3 minutes, and then appears in the card list of the cardholder.

deliveryMethod._id (use GET /fees/delivery-methods to find it), phoneNumber, country and embossName1 are required. productCode can only be R007 (the default). The card issuing fee and the delivery fee are blocked on the main account when you call this endpoint (debitAccountNumber, or the default main account), and are charged when the card is created. If the card cannot be created, the fees are unblocked. If the main account does not have enough money, the call is refused with 400. The card limit for prepaid physical cards is separate from the limit of normal physical cards.

A request that is not valid (for example a product that is not assigned to the company) is refused with 400 before anything is requested.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Cardholder _id — must resolve to a cardholder owned by the calling partner.

header Parameters
Idempotency-Key
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

Optional idempotency key to ensure safe retries for non-GET requests.

When provided, the API remembers your request and returns the exact same result if the same key is sent within 60 seconds. This protects against duplicate operations in case of network timeouts or accidental retries.

Recommended: Use a UUID v4 for each logical operation.

Response headers:

  • Same key + same request → original response + X-Idempotency-Replay: true
  • Same key + different request → 409 Conflict
  • Request still processing → 202 Accepted
Request Body schema: application/json
required
productCode
string
Default: "R007"
Value: "R007"

The prepaid physical card product. Only R007 is accepted.

required
object

How the card is sent (carrier). Take the _id from GET /fees/delivery-methods?country=XX (two-letter country code) — that call only lists methods available for the country; it is not the final charged fee by itself.

The carrier is read from the start of _id (dhl-… is DHL, pp_poczta-… is Poczta Post). That choice picks which fee rule is used (express vs normal). The delivery country (from deliveryAddressId, or from country when no address id is sent) then decides EEA vs non-EEA pricing. Any price you send on this object is ignored.

phoneNumber
required
string

Delivery contact phone.

country
required
string

ISO 3166-1 alpha-3 country code. Used for the delivery fee (EEA vs non-EEA) when deliveryAddressId is not sent. Send the country of the registered address.

deliveryAddressId
string

Where the card is sent: a saved address of the cardholder. When it is left out, the card goes to the cardholder's registered address and the fee uses country. When it is sent, that address is used and its own country is used for the fee (country is then ignored for pricing).

embossName1
required
string <= 22 characters

First line of text embossed on the card.

embossName2
string <= 19 characters

Optional second line of text embossed on the card.

nickname
string

Optional card nickname.

debitAccountNumber
string <= 34 characters

The MAIN account (IBAN) the issuing and delivery fees are charged from. It must belong to the cardholder (or to the company of a B2B cardholder), otherwise the request is refused with 400. Omitted uses the default main account.

Responses

Response Schema: application/json
message
string
object

Request samples

Content type
application/json
{
  • "productCode": "R007",
  • "nickname": "Travel card",
  • "deliveryMethod": {
    },
  • "phoneNumber": "+359888123456",
  • "country": "BGR",
  • "deliveryAddressId": "onboarding:6836df4c98653594cae54d99",
  • "embossName1": "ANA IVANOVA",
  • "embossName2": "ACME LTD",
  • "debitAccountNumber": "XX00XXXX0000000000000000"
}

Response samples

Content type
application/json
{
  • "message": "Prepaid physical card requested. The card will be created in a few minutes (2-3 minutes).",
  • "data": {
    }
}

List the prepaid card requests of a B2B cardholder

Returns the prepaid card requests of the cardholder, newest first, one page at a time (page and limit, up to 100 per page). A prepaid card is created in the background, so use this to see where each request is. Every item has a status and an isFinished flag. pagination tells whether there are more pages. A page or limit that is not a positive whole number is a 400.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Cardholder _id — must resolve to a cardholder owned by the calling partner.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number for pagination. Starts at 1. Default values depend on the endpoint: transactions default to 1, and audit/status-history endpoints default to 1.

limit
integer [ 1 .. 100 ]
Default: 100
Example: limit=20

Number of prepaid card requests per page. At most 100: a larger value is not refused, the page has 100 items.

sortBy
string
Default: "createdAt"
Value: "createdAt"

Field to sort by. Only createdAt for now; any other value sorts by createdAt.

sortOrder
string
Default: "desc"
Enum: "desc" "asc"

desc (newest first) or asc (oldest first). Any other value is desc.

Responses

Response Schema: application/json
count
integer

Number of requests on this page.

Array of objects (PrepaidCardRequestStatus)
object (Pagination)

Response samples

Content type
application/json
{
  • "count": 0,
  • "data": [
    ],
  • "pagination": {
    }
}

Get one prepaid card request of a B2B cardholder

Returns where one prepaid card request is. Ask again every few seconds until isFinished is true. When status is SUCCESS, cardKey is the key of the new card. When it is FAILED, contact PayNovus support and give the prepaidRequestId; statusMessage says so. A request that does not exist, or belongs to another cardholder, is a 404.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Cardholder _id — must resolve to a cardholder owned by the calling partner.

requestId
required
string

The prepaidRequestId that the prepaid card request answered with.

Responses

Response Schema: application/json
object (PrepaidCardRequestStatus)

Where one prepaid card request is.

prepaidRequestId
string

Id of the request.

cardKind
string
Enum: "virtual" "physical"
cardholderId
string

The cardholder the card is created for.

productCode
string
currency
string
status
string (PrepaidCardRequestStatusValue)
Enum: "PENDING" "SUCCESS" "FAILED"

Where a prepaid card request is. SUCCESS and FAILED are final.

  • PENDING — the card is not ready yet. The request is being processed, usually for 2-3 minutes.
  • SUCCESS — the card is ready. See cardKey.
  • FAILED — the request could not be completed. The reason is not shown; contact PayNovus support and give the prepaidRequestId.
isFinished
boolean

true for COMPLETED and FAILED. Nothing more will happen; stop asking.

statusMessage
string

A plain sentence that describes the status. For FAILED it tells you to contact PayNovus support and give the prepaidRequestId.

cardKey
string or null

The key of the card, once it exists. Use it with the /cards/{cardKey} endpoints.

feesReleased
boolean or null

Physical cards only: true when the fees that were blocked for the card were unblocked after a failure. null for virtual cards.

createdAt
string or null <date-time>
statusUpdatedAt
string or null <date-time>

Response samples

Content type
application/json
{
  • "data": {
    }
}

Individual Accounts

Endpoints for managing individual cardholders onboarded by the partner. All paths under this tag are scoped to the calling partner.

List individual accounts

Returns every individual onboarding owned by the authenticated partner in a single response. This endpoint does not paginate. The payload includes a count field and the full data array.

Authorizations:
JWTBearerAuth

Responses

Response Schema: application/json
count
integer
Array of objects (IndividualAccountSummary)

Response samples

Content type
application/json
{
  • "count": 0,
  • "data": [
    ]
}

Create individual account

Creates a partner-owned individual cardholder. The individual never logs into the CIP dashboard — the partner has its own dashboard for that; the record exists here only so PayNovus admins can see and control it on the partner's behalf.

Authorizations:
JWTBearerAuth
header Parameters
Idempotency-Key
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

Optional idempotency key to ensure safe retries for non-GET requests.

When provided, the API remembers your request and returns the exact same result if the same key is sent within 60 seconds. This protects against duplicate operations in case of network timeouts or accidental retries.

Recommended: Use a UUID v4 for each logical operation.

Response headers:

  • Same key + same request → original response + X-Idempotency-Replay: true
  • Same key + different request → 409 Conflict
  • Request still processing → 202 Accepted
Request Body schema: application/json
required
firstName
required
string <= 200 characters
middleName
required
string [ 2 .. 200 ] characters
lastName
required
string <= 200 characters
country
required
string = 2 characters

ISO 3166-1 alpha-2 country code

city
required
string <= 100 characters
stateProvince
string <= 100 characters

Optional state / province / region.

zipCode
required
string <= 20 characters
buildingNumber
required
string <= 100 characters
idType
required
string
Enum: "PASSPORT" "DRIVER_LICENSE" "RESIDENCE_CARD" "MINOR_WITHOUT_ID" "OTHER"
address1
required
string <= 200 characters
address2
string <= 200 characters

Optional secondary address line.

passportNumber
required
string <= 40 characters
issuingDate
required
string

Document issue date in yyyy-mm-dd format. Must be on or before validityDate.

validityDate
required
string

Document expiry date in yyyy-mm-dd format.

passportCountry
required
string = 2 characters

ISO 3166-1 alpha-2 country code that issued the document

taxCountry
string = 2 characters

Optional ISO 3166-1 alpha-2 country code for tax residency. Must be exactly 2 letters if provided.

taxIdNumber
string <= 40 characters

Optional tax identification number. Defaults to passportNumber when omitted.

birthCountry
required
string = 2 characters
birthDate
required
string

yyyy-mm-dd

nationality
required
string = 2 characters
phone
required
string [ 10 .. 20 ] characters
email
required
string <email> <= 100 characters

Responses

Response Schema: application/json
message
required
string

Human-readable success message.

individualId
required
string

Mongo _id of the newly created IndividualOnboarding record.

Request samples

Content type
application/json
{
  • "firstName": "Casey",
  • "middleName": "Quinn",
  • "lastName": "Sample",
  • "country": "PL",
  • "city": "Samplecity",
  • "stateProvince": "Sampleregion",
  • "zipCode": "00-000",
  • "buildingNumber": "0",
  • "idType": "PASSPORT",
  • "address1": "Sample Street 0",
  • "passportNumber": "X0000000",
  • "issuingDate": "2020-01-01",
  • "validityDate": "2030-01-01",
  • "passportCountry": "PL",
  • "taxCountry": "PL",
  • "taxIdNumber": "0000000000",
  • "birthCountry": "PL",
  • "birthDate": "1990-01-01",
  • "nationality": "PL",
  • "phone": "+10000000000",
  • "email": "partner.example@example.com"
}

Response samples

Content type
application/json
{
  • "message": "Individual account created successfully",
  • "individualId": "string"
}

Get individual account

Returns the individual onboarding identified by :id. The record must be owned by your partner — otherwise the response is 404 Not Found (no enumeration).

For B2B tenants, cardholders live under the tenant and are listed at GET /business/accounts/{b2bAccountId}/cardholders. Each B2B cardholder can also be inspected individually by id via the cardholder page at GET /business/cardholders/{id} — useful when you already have a cardholder id and want the full onboarding document without re-listing the tenant.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Individual identifier

Responses

Response Schema: application/json
message
string
object (IndividualAccount)

Flat partner-facing individual account view returned by GET /api/partner/individual/accounts/{id}. The endpoint flattens the onboarding into a single-level payload — no nested personalInfo / address / idDocument / taxInfo sub-objects. Fields whose source value is missing are absent from the response.

Array of objects (AccountCard)
balance
number

Live availableBalance for the resolved IBAN. Returns 0 when no IBAN exists or the upstream call fails.

Response samples

Content type
application/json
{
  • "message": "string",
  • "accounts": {
    },
  • "cards": [
    ],
  • "balance": 0
}

List cards for an individual

Returns every active card owned by the given individual in one response. This endpoint does not paginate and returns { count, data }.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Individual onboarding _id

Responses

Response Schema: application/json
count
integer

Number of cards in data.

Array of objects (AccountCard)

Response samples

Content type
application/json
{
  • "count": 0,
  • "data": [
    ]
}

Get live balances for every IBAN linked to the individual

Returns the live availableBalance for each IBAN linked to the individual.

Per-IBAN failure handling. Any IBAN whose balance cannot be resolved is surfaced in the response with status: "error" and an errorMessage field — failures are never silently reported as zero. The overall HTTP status remains 200 so a partner UI can still render the IBANs that succeeded.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Individual identifier — must be owned by the calling partner.

Responses

Response Schema: application/json
success
boolean
count
integer
Array of objects (BalanceEntry)

Response samples

Content type
application/json
{
  • "success": true,
  • "count": 0,
  • "data": [
    ]
}

Create virtual card for an individual

Issues a virtual card under the given individual. The card is created on the partner/individual ownership chain.

The request body is optional. Every field has a sensible server-side default — omitting the body entirely issues a card with the cardholder's primary IBAN, currency, and the default virtual-card product (R002). Pass any subset of the fields below to override individual defaults; embossName1, embossName2, currencyCode, accNo, and productCode are all optional.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string
header Parameters
Idempotency-Key
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

Optional idempotency key to ensure safe retries for non-GET requests.

When provided, the API remembers your request and returns the exact same result if the same key is sent within 60 seconds. This protects against duplicate operations in case of network timeouts or accidental retries.

Recommended: Use a UUID v4 for each logical operation.

Response headers:

  • Same key + same request → original response + X-Idempotency-Replay: true
  • Same key + different request → 409 Conflict
  • Request still processing → 202 Accepted
Request Body schema: application/json
optional
embossName1
string <= 22 characters

First line of text embossed on the card.

currencyCode
integer

Numeric ISO 4217 currency code. Falls back to the cardholder's debit-account currency when omitted.

accNo
string

IBAN to link the card to. Falls back to the cardholder's primary account when omitted.

productCode
string

Product code. Defaults to R002 for individual cardholders and R004 for B2B cardholders when omitted.

Responses

Response Schema: application/json
success
required
boolean
message
required
string
required
object (PartnerVirtualIssuedCard)

Slim card shape returned by the partner-individual virtual-card creation endpoint (POST /api/partner/individual/accounts/{id}/cards/virtual).

The card-issuing platform's virtual-card creation response carries only these. Lifecycle / shipping fields (set_pin, set_password, deliveryMethod, deliveryAddress, isAdminBlocked, _id, createdAt, updatedAt, __v) are omitted on the virtual path — call GET /api/partner/cards/{id} for the full record.

Request samples

Content type
application/json
{
  • "embossName1": "CASEY SAMPLE",
  • "currencyCode": 978,
  • "accNo": "XX00XXXX0000000000000000",
  • "productCode": "R002"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Virtual card created successfully",
  • "data": {
    }
}

Create physical card for an individual

Issues a physical card under the given individual.

Only deliveryMethod._id is required. The other deliveryMethod fields and productCode, embossName1, embossName2, nickname, currencyCode, accNo, and country are all optional — pass any subset to override individual defaults; omit the body entirely (except deliveryMethod._id) and the cardholder's stored values are used.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string
header Parameters
Idempotency-Key
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

Optional idempotency key to ensure safe retries for non-GET requests.

When provided, the API remembers your request and returns the exact same result if the same key is sent within 60 seconds. This protects against duplicate operations in case of network timeouts or accidental retries.

Recommended: Use a UUID v4 for each logical operation.

Response headers:

  • Same key + same request → original response + X-Idempotency-Replay: true
  • Same key + different request → 409 Conflict
  • Request still processing → 202 Accepted
Request Body schema: application/json
optional
productCode
string

Product code. Defaults to R001 when omitted.

embossName1
string <= 22 characters

First line of text embossed on the card. Defaults to the cardholder's stored embossedName1 when omitted.

embossName2
string <= 19 characters

Second line of text embossed on the card. Defaults to the cardholder's stored embossedName2 when omitted.

nickname
string

Optional card nickname shown in the partner/individual UI.

object

Delivery method for the physical card. The accepted prefixes are pp_poczta-{id} (Poczta Post) and dhl-{id} (DHL). Only _id is required — every other field has a sensible server-side default derived from the _id prefix.

currencyCode
integer

Numeric ISO 4217 currency code. Falls back to the resolved debit account currency when omitted.

accNo
string

IBAN to link the card to. Falls back to the cardholder's primary account when omitted.

country
string

ISO 3166-1 country code (alpha-2 or alpha-3) for the delivery destination. Optional — defaults to the cardholder's country.

Responses

Response Schema: application/json
success
required
boolean
message
required
string
required
object (PartnerPhysicalIssuedCard)

Full card shape returned by the partner-individual physical-card creation endpoint (POST /api/partner/individual/accounts/{id}/cards/physical).

Mirrors the full AccountCard document with all lifecycle and shipping fields populated. See AccountCard for the canonical field-by-field description.

Request samples

Content type
application/json
{
  • "productCode": "R001",
  • "embossName1": "CASEY SAMPLE",
  • "embossName2": "string",
  • "nickname": "string",
  • "deliveryMethod": {
    },
  • "currencyCode": 978,
  • "accNo": "XX00XXXX0000000000000000",
  • "country": "BGR"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Physical card created successfully",
  • "data": {
    }
}

Request a prepaid virtual card for an individual

Requests a prepaid virtual card. The card is not created in this call. The call checks the request and answers 200 with status: "PENDING". The card is created in the background, usually within 2-3 minutes, and then appears in the card list of the cardholder.

The body is optional. productCode can only be R008 (the default), and the currency is EUR.

A request that is not valid (for example a product that is not assigned to the company) is refused with 400 before anything is requested.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Individual _id — must resolve to an individual owned by the calling partner.

header Parameters
Idempotency-Key
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

Optional idempotency key to ensure safe retries for non-GET requests.

When provided, the API remembers your request and returns the exact same result if the same key is sent within 60 seconds. This protects against duplicate operations in case of network timeouts or accidental retries.

Recommended: Use a UUID v4 for each logical operation.

Response headers:

  • Same key + same request → original response + X-Idempotency-Replay: true
  • Same key + different request → 409 Conflict
  • Request still processing → 202 Accepted
Request Body schema: application/json
optional
productCode
string
Default: "R008"
Value: "R008"

The prepaid virtual card product. Only R008 is accepted.

currencyCode
string
Default: "EUR"
Value: "EUR"

Currency of the card. Only EUR is accepted.

nickname
string

Optional card nickname.

Responses

Response Schema: application/json
message
string
object

Request samples

Content type
application/json
{
  • "nickname": "Online shopping"
}

Response samples

Content type
application/json
{
  • "message": "Prepaid physical card requested. The card will be created in a few minutes (2-3 minutes).",
  • "data": {
    }
}

Request a prepaid physical card for an individual

Requests a prepaid physical card. The card is not created in this call. The call checks the request and answers 200 with status: "PENDING". The card is created in the background, usually within 2-3 minutes, and then appears in the card list of the cardholder.

deliveryMethod._id (use GET /fees/delivery-methods to find it), phoneNumber, country and embossName1 are required. productCode can only be R007 (the default). The card issuing fee and the delivery fee are blocked on the main account when you call this endpoint (debitAccountNumber, or the default main account), and are charged when the card is created. If the card cannot be created, the fees are unblocked. If the main account does not have enough money, the call is refused with 400. The card limit for prepaid physical cards is separate from the limit of normal physical cards.

A request that is not valid (for example a product that is not assigned to the company) is refused with 400 before anything is requested.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Individual _id — must resolve to an individual owned by the calling partner.

header Parameters
Idempotency-Key
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

Optional idempotency key to ensure safe retries for non-GET requests.

When provided, the API remembers your request and returns the exact same result if the same key is sent within 60 seconds. This protects against duplicate operations in case of network timeouts or accidental retries.

Recommended: Use a UUID v4 for each logical operation.

Response headers:

  • Same key + same request → original response + X-Idempotency-Replay: true
  • Same key + different request → 409 Conflict
  • Request still processing → 202 Accepted
Request Body schema: application/json
required
productCode
string
Default: "R007"
Value: "R007"

The prepaid physical card product. Only R007 is accepted.

required
object

How the card is sent (carrier). Take the _id from GET /fees/delivery-methods?country=XX (two-letter country code) — that call only lists methods available for the country; it is not the final charged fee by itself.

The carrier is read from the start of _id (dhl-… is DHL, pp_poczta-… is Poczta Post). That choice picks which fee rule is used (express vs normal). The delivery country (from deliveryAddressId, or from country when no address id is sent) then decides EEA vs non-EEA pricing. Any price you send on this object is ignored.

phoneNumber
required
string

Delivery contact phone.

country
required
string

ISO 3166-1 alpha-3 country code. Used for the delivery fee (EEA vs non-EEA) when deliveryAddressId is not sent. Send the country of the registered address.

deliveryAddressId
string

Where the card is sent: a saved address of the cardholder. When it is left out, the card goes to the cardholder's registered address and the fee uses country. When it is sent, that address is used and its own country is used for the fee (country is then ignored for pricing).

embossName1
required
string <= 22 characters

First line of text embossed on the card.

embossName2
string <= 19 characters

Optional second line of text embossed on the card.

nickname
string

Optional card nickname.

debitAccountNumber
string <= 34 characters

The MAIN account (IBAN) the issuing and delivery fees are charged from. It must belong to the cardholder (or to the company of a B2B cardholder), otherwise the request is refused with 400. Omitted uses the default main account.

Responses

Response Schema: application/json
message
string
object

Request samples

Content type
application/json
{
  • "productCode": "R007",
  • "nickname": "Travel card",
  • "deliveryMethod": {
    },
  • "phoneNumber": "+359888123456",
  • "country": "BGR",
  • "deliveryAddressId": "onboarding:6836df4c98653594cae54d99",
  • "embossName1": "ANA IVANOVA",
  • "embossName2": "ACME LTD",
  • "debitAccountNumber": "XX00XXXX0000000000000000"
}

Response samples

Content type
application/json
{
  • "message": "Prepaid physical card requested. The card will be created in a few minutes (2-3 minutes).",
  • "data": {
    }
}

List the prepaid card requests of an individual

Returns the prepaid card requests of the cardholder, newest first, one page at a time (page and limit, up to 100 per page). A prepaid card is created in the background, so use this to see where each request is. Every item has a status and an isFinished flag. pagination tells whether there are more pages. A page or limit that is not a positive whole number is a 400.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Individual _id — must resolve to an individual owned by the calling partner.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number for pagination. Starts at 1. Default values depend on the endpoint: transactions default to 1, and audit/status-history endpoints default to 1.

limit
integer [ 1 .. 100 ]
Default: 100
Example: limit=20

Number of prepaid card requests per page. At most 100: a larger value is not refused, the page has 100 items.

sortBy
string
Default: "createdAt"
Value: "createdAt"

Field to sort by. Only createdAt for now; any other value sorts by createdAt.

sortOrder
string
Default: "desc"
Enum: "desc" "asc"

desc (newest first) or asc (oldest first). Any other value is desc.

Responses

Response Schema: application/json
count
integer

Number of requests on this page.

Array of objects (PrepaidCardRequestStatus)
object (Pagination)

Response samples

Content type
application/json
{
  • "count": 0,
  • "data": [
    ],
  • "pagination": {
    }
}

Get one prepaid card request of an individual

Returns where one prepaid card request is. Ask again every few seconds until isFinished is true. When status is SUCCESS, cardKey is the key of the new card. When it is FAILED, contact PayNovus support and give the prepaidRequestId; statusMessage says so. A request that does not exist, or belongs to another cardholder, is a 404.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Individual _id — must resolve to an individual owned by the calling partner.

requestId
required
string

The prepaidRequestId that the prepaid card request answered with.

Responses

Response Schema: application/json
object (PrepaidCardRequestStatus)

Where one prepaid card request is.

prepaidRequestId
string

Id of the request.

cardKind
string
Enum: "virtual" "physical"
cardholderId
string

The cardholder the card is created for.

productCode
string
currency
string
status
string (PrepaidCardRequestStatusValue)
Enum: "PENDING" "SUCCESS" "FAILED"

Where a prepaid card request is. SUCCESS and FAILED are final.

  • PENDING — the card is not ready yet. The request is being processed, usually for 2-3 minutes.
  • SUCCESS — the card is ready. See cardKey.
  • FAILED — the request could not be completed. The reason is not shown; contact PayNovus support and give the prepaidRequestId.
isFinished
boolean

true for COMPLETED and FAILED. Nothing more will happen; stop asking.

statusMessage
string

A plain sentence that describes the status. For FAILED it tells you to contact PayNovus support and give the prepaidRequestId.

cardKey
string or null

The key of the card, once it exists. Use it with the /cards/{cardKey} endpoints.

feesReleased
boolean or null

Physical cards only: true when the fees that were blocked for the card were unblocked after a failure. null for virtual cards.

createdAt
string or null <date-time>
statusUpdatedAt
string or null <date-time>

Response samples

Content type
application/json
{
  • "data": {
    }
}

List audit logs for an individual

Returns the audit log entries scoped to the given individual. This endpoint is paginated. The default is page=1 and limit=50. There is currently no hard server-side cap on the limit value in the Partner API implementation. The response contains data and a pagination object with total, page, limit, and pages.

Filters can be combined: ?action=LOCK_CARD&result=SUCCESS&from=2025-01-01.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number for pagination. Starts at 1. Default values depend on the endpoint: transactions default to 1, and audit/status-history endpoints default to 1.

limit
integer >= 1
Default: 50
Example: limit=50

Number of audit-log or card-status-history records to return per page. Defaults to 50. There is currently no enforced maximum limit value in the Partner API implementation. Pass a larger value directly, for example ?page=1&limit=3000.

from
string <date-time>

Inclusive lower bound on the entry's createdAt (ISO 8601, e.g. 2025-01-01 or 2025-01-01T00:00:00Z). Invalid values yield 400 Bad Request.

to
string <date-time>

Inclusive upper bound on the entry's createdAt (ISO 8601, e.g. 2025-12-31 or 2025-12-31T23:59:59Z). Invalid values yield 400 Bad Request.

sort
string

Sort order, comma-separated field:direction pairs (use - for descending). Defaults to -createdAt when omitted. Example: ?sort=-createdAt.

cardId
string

Filter by card cardKey. The alias card is also accepted.

action
string

Filter by action name (e.g. CREATE_VIRTUAL_CARD).

result
string
Enum: "SUCCESS" "FAILED"

Filter by outcome.

Responses

Response Schema: application/json
success
boolean
Array of objects (AuditLogEntry)
object (Pagination)

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "pagination": {
    }
}

Card status history for an individual

Returns every card-status change recorded for this individual. This endpoint is paginated. The default is page=1 and limit=50. There is currently no hard server-side cap on the limit value in the Partner API implementation. The response contains data and a pagination object with total, page, limit, and pages.

Filters can be combined: ?fromStatus=ACTIVE&toStatus=LOCKED&triggeredBy=PARTNER.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number for pagination. Starts at 1. Default values depend on the endpoint: transactions default to 1, and audit/status-history endpoints default to 1.

limit
integer >= 1
Default: 50
Example: limit=50

Number of audit-log or card-status-history records to return per page. Defaults to 50. There is currently no enforced maximum limit value in the Partner API implementation. Pass a larger value directly, for example ?page=1&limit=3000.

from
string <date-time>

Inclusive lower bound on the entry's createdAt (ISO 8601, e.g. 2025-01-01 or 2025-01-01T00:00:00Z). Invalid values yield 400 Bad Request.

to
string <date-time>

Inclusive upper bound on the entry's createdAt (ISO 8601, e.g. 2025-12-31 or 2025-12-31T23:59:59Z). Invalid values yield 400 Bad Request.

sort
string

Sort order, comma-separated field:direction pairs (use - for descending). Defaults to -createdAt when omitted. Example: ?sort=-createdAt.

cardId
string

Filter by card cardKey. The alias card is also accepted.

fromStatus
string

Filter by the card status before the change. Accepts either the status name (e.g. ACTIVE) or the raw status code (e.g. WW).

toStatus
string

Filter by the card status after the change. Accepts either the status name (e.g. LOCKED) or the raw status code (e.g. WL).

triggeredBy
string
Enum: "PARTNER" "USER" "SYSTEM"

Filter by who drove the status change.

triggeredByUserId
string

Filter by the dashboard user that drove the change (only set when triggeredBy=USER). Pass a User ObjectId.

Responses

Response Schema: application/json
Array of objects (CardStatusHistoryEntryRaw)
object (Pagination)

Response samples

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

List transactions for an individual

Paginated transactions for the individual. Defaults: page=1, limit=10. No hard server-side cap on limit.

The response contains transactions and a provider pagination object.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number for pagination. Starts at 1. Default values depend on the endpoint: transactions default to 1, and audit/status-history endpoints default to 1.

limit
integer >= 1
Default: 10
Example: limit=10

Number of transactions to return per page. Defaults to 10. There is currently no enforced maximum limit value in the Partner API implementation. Pass a larger value directly, for example ?page=1&limit=3000, unless the upstream provider rejects it.

Responses

Response Schema: application/json
Array of objects (Transaction)
object

Response samples

Content type
application/json
{
  • "transactions": [
    ],
  • "pagination": {
    }
}

Transactions

Partner-wide transaction history aggregation. Endpoints under this tag scope their results to the calling partner — the partner physically cannot see another partner's transactions, and ownership-mismatch responses use a non-enumerating 404 envelope rather than 403.

List all transactions across the partner's accounts

Returns every transaction the authenticated partner is allowed to see, aggregated across all of its linked individual onboardings (and any B2B-shared tenant accounts that those onboardings resolve to).

This endpoint is paginated. The default is page=1 and limit=10. There is currently no hard server-side cap on limit.

Pass the values as query parameters, for example ?page=2&limit=3000. The response contains the transaction data and pagination metadata including the total number of matching rows and total pages.

Filter rules. The two filters are mutually exclusive — passing both at once returns 400:

  • ?accountIdentification=… — narrow to one or more IBANs. Accepts a single IBAN, a comma-separated list (?accountIdentification=DE1,DE2), or repeated keys (?accountIdentification=DE1&accountIdentification=DE2). Any IBAN the partner does not own is silently excluded from the result. If every supplied IBAN is foreign to the partner, the endpoint returns 404 "IBAN not found."
  • ?cardId=<cardKey> — narrow to a single card. Exactly one cardKey is allowed; passing multiple (repeated keys or comma-separated) returns 400. An unowned cardKey returns 404 "Card not found!".

When neither filter is supplied, the partner's full owned-IBAN union is queried. If the partner has zero owned IBANs the endpoint returns 400.

Empty result sets (no rows in the date range) are returned with HTTP 200 and an empty data array — mirroring /individual/accounts/{id}/transactions.

Authorizations:
JWTBearerAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number for pagination. Starts at 1. Default values depend on the endpoint: transactions default to 1, and audit/status-history endpoints default to 1.

limit
integer >= 1
Default: 10
Example: limit=10

Number of transactions to return per page. Defaults to 10. There is currently no enforced maximum limit value in the Partner API implementation. Pass a larger value directly, for example ?page=1&limit=3000, unless the upstream provider rejects it.

accountIdentification
string

One IBAN, or several (comma-separated, or repeated keys). Only IBANs the partner owns are forwarded; foreign IBANs are silently excluded. Mutually exclusive with cardId.

cardId
string

Single card cardKey. Mutually exclusive with accountIdentification.

Responses

Response Schema: application/json
Array of objects (Transaction)
object

Response samples

Content type
application/json
{
  • "transactions": [
    ],
  • "pagination": {
    }
}

List live balances for every IBAN the partner owns

Returns the live availableBalance for every IBAN the calling partner owns. The same IBAN can appear via two onboardings (e.g. a cardholder who is also a tenant admin) — results are deduplicated by accountNumber so each IBAN appears exactly once.

Per-IBAN failures are surfaced in the response with status: "error" and an errorMessage field — never silently zeroed. The overall HTTP status remains 200 so a partner UI can still render the IBANs that succeeded.

The optional ?iban=… query parameter narrows the result set to a single IBAN.

Authorizations:
JWTBearerAuth
query Parameters
iban
string

Optional IBAN filter.

Responses

Response Schema: application/json
success
boolean
count
integer
Array of objects (BalanceEntry)

Response samples

Content type
application/json
{
  • "success": true,
  • "count": 0,
  • "data": [
    ]
}

Get the live balance for a single IBAN

Live availableBalance for a single IBAN the partner owns. Same failure semantics as /balances: status: "error" on a per-IBAN failure.

Authorizations:
JWTBearerAuth
path Parameters
iban
required
string

IBAN whose balance to fetch. Must belong to the calling partner; foreign IBANs return 404 without enumeration.

Responses

Response Schema: application/json
success
boolean
count
integer
Array of objects (BalanceEntry)

Response samples

Content type
application/json
{
  • "success": true,
  • "count": 0,
  • "data": [
    ]
}

Cards

Card-level endpoints that operate on a single card. The :id path parameter is the cardKey (for example KDRYV0XXXXXXXXXX). Every endpoint under /cards/:id/... is scoped to the calling partner.

List all partner cards

Returns every card owned by the authenticated partner across all account types (B2B + individual). Not tenant-scoped per-card — this is a full partner-wide list in a single response. There is no pagination on this endpoint; the payload includes a count value and the complete data array.

Authorizations:
JWTBearerAuth
query Parameters
status
string (CardStatus)
Enum Description
ACTIVE

Card is open and can transact.

LOCKED

Cardholder- or admin-initiated lock. Reversible via unlock.

BLOCKED

Admin-initiated block. Reversible by an admin.

EXPIRED

Card has reached its expiry date.

CLOSED

Card is permanently closed.

ORDERED

Card has been ordered but not yet produced / activated.

INACTIVE

Card exists but is currently disabled (not in use).

RESTRICTED

Card is online-only (e.g. no ATM). Reversible.

Filter by card status.

type
string
Enum: "virtual" "physical"

virtual or physical

search
string

Case-insensitive search on cardMask / name

Responses

Response Schema: application/json
count
integer

Number of cards in data.

Array of objects (PartnerCardListItem)

Cards sorted by createdAt descending. Each entry is a PartnerCardListItem with card-only fields. Foreign-key references (onboarding, b2bClient) are returned as bare ObjectId strings, not populated sub-documents. Resolve them via /cardholders/{id} or /business/accounts/{b2bAccountId}. No account-level fields (personal info, addresses, permissions, audit logs, etc.) are exposed on this endpoint.

Response samples

Content type
application/json
{
  • "count": 0,
  • "data": [
    ]
}

List the prepaid card requests of all your cardholders

Returns the prepaid card requests of every cardholder of the partner: its own individuals and the cardholders of its business accounts. No cardholder id is needed. Newest first, one page at a time (page and limit, up to 100 per page). Each item has a cardholderId, a status and an isFinished flag. pagination tells whether there are more pages. A page or limit that is not a positive whole number is a 400.

Authorizations:
JWTBearerAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number for pagination. Starts at 1. Default values depend on the endpoint: transactions default to 1, and audit/status-history endpoints default to 1.

limit
integer [ 1 .. 100 ]
Default: 100
Example: limit=20

Number of prepaid card requests per page. At most 100: a larger value is not refused, the page has 100 items.

sortBy
string
Default: "createdAt"
Value: "createdAt"

Field to sort by. Only createdAt for now; any other value sorts by createdAt.

sortOrder
string
Default: "desc"
Enum: "desc" "asc"

desc (newest first) or asc (oldest first). Any other value is desc.

Responses

Response Schema: application/json
count
integer

Number of requests on this page.

Array of objects (PrepaidCardRequestStatus)
object (Pagination)

Response samples

Content type
application/json
{
  • "count": 0,
  • "data": [
    ],
  • "pagination": {
    }
}

Get the balance of prepaid cards

Returns the money on each prepaid card asked for. Up to 50 card keys per request, comma separated. One answer per key, in the order asked.

A card that does not exist, is not a prepaid card, or does not belong to your partner is answered with found: false - the same answer in each case. availableBalance: null means the balance could not be read right now; it is not zero.

Authorizations:
JWTBearerAuth
query Parameters
cardKeys
required
string
Example: cardKeys=1000234567,1000234568

Comma separated card keys (cardKey), up to 50.

Responses

Response Schema: application/json
Array of objects (PrepaidCardBalance)
Array
cardKey
string
found
boolean

False when the card does not exist, is not prepaid, or is not yours. The other fields are then empty.

currency
string or null
availableBalance
number or null

Null when the balance could not be read right now (not zero).

message
string

Only when found is false.

Response samples

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

Get card details

Returns full card details. Does not include the PAN or CVV — use the dedicated sensitive endpoints below for those.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Card cardKey (for example KDRYV0XXXXXXXXXX).

Responses

Response Schema: application/json
object (PartnerCardDetails)

Full card details returned by GET /api/partner/cards/{id}.

Card-only — does not include onboarding or b2bClient references. Resolve the cardholder via GET /api/partner/cardholders/{id}, GET /api/partner/business/cardholders/{id}, or GET /api/partner/business/accounts/{b2bAccountId}.

cardHash
string

128-char hex card hash.

cardKey
string

16-char card key. The user-facing identifier used as :id in /api/partner/cards/{id} paths.

cardUuid
string or null

Card-issuing platform internal UUID.

cardMask
string

Masked card number (e.g. 446614******9605).

expDate
string

Card expiry as MM/YYYY.

issueDate
string <date>

Card issue date as yyyy-MM-dd.

status
string (CardStatus)
Enum Description
ACTIVE

Card is open and can transact.

LOCKED

Cardholder- or admin-initiated lock. Reversible via unlock.

BLOCKED

Admin-initiated block. Reversible by an admin.

EXPIRED

Card has reached its expiry date.

CLOSED

Card is permanently closed.

ORDERED

Card has been ordered but not yet produced / activated.

INACTIVE

Card exists but is currently disabled (not in use).

RESTRICTED

Card is online-only (e.g. no ATM). Reversible.

Card lifecycle state as returned by IT Card.

statusCode
string

Raw card status code from the card-issuing platform (e.g. 00, S1, L1).

terminating
boolean

true while the card is mid-termination.

productCode
string

4-char product code (e.g. R004).

productDesc
string or null

Human-readable product name (e.g. RYVYL VISA BUSINESS DEBIT VTL).

holder
string

Card holder client code (e.g. RYVL-1720_1).

Array of objects (PartnerCardAccount)

One or more accounts the card is linked to.

embossName1
string or null

Embossed cardholder name (line 1, max 22 chars).

embossName2
string or null

Embossed company name (line 2, max 19 chars).

source
string

Card source. Common values: NEW, RENEW, REPLACE, RESIGN.

kind
string
Enum: "DEBIT" "CREDIT" "PREPAID"

Card kind.

main
boolean

true for the cardholder's primary card.

Array of objects (PartnerCardLimit)

Per-card limit rows.

visual
string

Visual code (usually equal to productCode).

visualDesc
string or null

Human-readable visual description.

tokenized
boolean

true if the card has been tokenized (e.g. for Apple/Google Pay).

object (PartnerCardDelivery)

Card delivery metadata. Only deliveryType is reliably present — branch fields are populated only for branch-pickup deliveries.

contactless
boolean

true if contactless transactions are enabled.

cardTechnologyMode
string

Card technology mode. Common values: VIRTUAL, PHYSICAL, DUAL.

creationDate
string <date>

Card creation date as yyyy-MM-dd.

creationUser
string or null

Username/operator that created the card.

oldPlastic
string or null

Previous card plastic reference. Only set after a replace/resign.

autoRenewal
boolean

true if the card auto-renews on expiry.

saleChannelCode
string or null

3-char sale channel code.

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get card status

Returns the current card status + status code. Only status and statusCode are returned (no cardKey, since the cardKey is already in the URL path).

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Card cardKey (for example KDRYV0XXXXXXXXXX).

Responses

Response Schema: application/json
object (CardStatusOnlyResponse)

Body returned by GET /api/partner/cards/{id}/status.

No cardKey — the status endpoint returns just the status name + status code. The cardKey is already known to the caller from the URL path.

status
string (CardStatus)
Enum Description
ACTIVE

Card is open and can transact.

LOCKED

Cardholder- or admin-initiated lock. Reversible via unlock.

BLOCKED

Admin-initiated block. Reversible by an admin.

EXPIRED

Card has reached its expiry date.

CLOSED

Card is permanently closed.

ORDERED

Card has been ordered but not yet produced / activated.

INACTIVE

Card exists but is currently disabled (not in use).

RESTRICTED

Card is online-only (e.g. no ATM). Reversible.

Card lifecycle state as returned by IT Card.

statusCode
string

Raw card status code from the card-issuing platform (e.g. 00, S1, WL).

Response samples

Content type
application/json
{
  • "data": {
    }
}

Lock card

Locks the card. The card stays in the holder's possession but cannot authorize transactions. The request body is optional; send an empty JSON object or omit it.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Card cardKey (for example KDRYV0XXXXXXXXXX).

Request Body schema: application/json
optional
expDate
required
string^(0[1-9]|1[0-2])\/\d{4}$

Card expiration in MM/YYYY

reason
string

Audit reason (free-form)

Responses

Response Schema: application/json
object (CardActionResponse)

Response returned by every card-lifecycle endpoint that does not move the card to a new cardKey — i.e. lock, unlock, activate, temporary-lock-card, restrict, restrict-card-as-lost, restrict-card-as-stolen, restrict-card-as-closed, restrict-card-fraud, embossName, and resetPinTries.

No cardMask on this shape — use GET /api/partner/cards/{id} to fetch it.

Required: cardHash, cardKey, expDate, status, statusCode, kind, productCode. Optional (productDesc, main, holder, accNo, embossName1, embossName2): present on most responses but not strictly guaranteed.

cardHash
string

128-char hex card hash.

cardKey
string

16-char card key (the same :id from the request).

expDate
string

Card expiry as MM/YYYY.

status
string (CardStatus)
Enum Description
ACTIVE

Card is open and can transact.

LOCKED

Cardholder- or admin-initiated lock. Reversible via unlock.

BLOCKED

Admin-initiated block. Reversible by an admin.

EXPIRED

Card has reached its expiry date.

CLOSED

Card is permanently closed.

ORDERED

Card has been ordered but not yet produced / activated.

INACTIVE

Card exists but is currently disabled (not in use).

RESTRICTED

Card is online-only (e.g. no ATM). Reversible.

Card lifecycle state as returned by IT Card.

statusCode
string

Raw card status code from the card-issuing platform (e.g. 00, BL, KZ).

kind
string
Enum: "DEBIT" "CREDIT" "PREPAID"

Card kind (form-factor family). There is no type field.

productCode
string

4-char product code (e.g. R004, DCT).

productDesc
string or null

Human-readable product description (e.g. RYVYL VISA BUSINESS DEBIT VTL).

main
boolean or null

true if this is the cardholder's primary card.

holder
string or null

Cardholder client code (e.g. RYVL-1720_1).

accNo
string or null

IBAN of the account that funds the card.

embossName1
string or null <= 26 characters

Embossed cardholder name (line 1).

embossName2
string or null <= 30 characters

Embossed company name (line 2).

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "data": {
    }
}

Unlock card

Unlocks a previously-locked card. The request body is optional.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Card cardKey (for example KDRYV0XXXXXXXXXX).

Request Body schema: application/json
optional
expDate
required
string^(0[1-9]|1[0-2])\/\d{4}$

Card expiration in MM/YYYY

reason
string

Audit reason (free-form)

Responses

Response Schema: application/json
object (CardActionResponse)

Response returned by every card-lifecycle endpoint that does not move the card to a new cardKey — i.e. lock, unlock, activate, temporary-lock-card, restrict, restrict-card-as-lost, restrict-card-as-stolen, restrict-card-as-closed, restrict-card-fraud, embossName, and resetPinTries.

No cardMask on this shape — use GET /api/partner/cards/{id} to fetch it.

Required: cardHash, cardKey, expDate, status, statusCode, kind, productCode. Optional (productDesc, main, holder, accNo, embossName1, embossName2): present on most responses but not strictly guaranteed.

cardHash
string

128-char hex card hash.

cardKey
string

16-char card key (the same :id from the request).

expDate
string

Card expiry as MM/YYYY.

status
string (CardStatus)
Enum Description
ACTIVE

Card is open and can transact.

LOCKED

Cardholder- or admin-initiated lock. Reversible via unlock.

BLOCKED

Admin-initiated block. Reversible by an admin.

EXPIRED

Card has reached its expiry date.

CLOSED

Card is permanently closed.

ORDERED

Card has been ordered but not yet produced / activated.

INACTIVE

Card exists but is currently disabled (not in use).

RESTRICTED

Card is online-only (e.g. no ATM). Reversible.

Card lifecycle state as returned by IT Card.

statusCode
string

Raw card status code from the card-issuing platform (e.g. 00, BL, KZ).

kind
string
Enum: "DEBIT" "CREDIT" "PREPAID"

Card kind (form-factor family). There is no type field.

productCode
string

4-char product code (e.g. R004, DCT).

productDesc
string or null

Human-readable product description (e.g. RYVYL VISA BUSINESS DEBIT VTL).

main
boolean or null

true if this is the cardholder's primary card.

holder
string or null

Cardholder client code (e.g. RYVL-1720_1).

accNo
string or null

IBAN of the account that funds the card.

embossName1
string or null <= 26 characters

Embossed cardholder name (line 1).

embossName2
string or null <= 30 characters

Embossed company name (line 2).

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "data": {
    }
}

Activate card

Activates a freshly-issued card. The request body is optional.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Card cardKey (for example KDRYV0XXXXXXXXXX).

Request Body schema: application/json
optional
expDate
required
string^(0[1-9]|1[0-2])\/\d{4}$

Card expiration in MM/YYYY

reason
string

Audit reason (free-form)

Responses

Response Schema: application/json
object (CardActionResponse)

Response returned by every card-lifecycle endpoint that does not move the card to a new cardKey — i.e. lock, unlock, activate, temporary-lock-card, restrict, restrict-card-as-lost, restrict-card-as-stolen, restrict-card-as-closed, restrict-card-fraud, embossName, and resetPinTries.

No cardMask on this shape — use GET /api/partner/cards/{id} to fetch it.

Required: cardHash, cardKey, expDate, status, statusCode, kind, productCode. Optional (productDesc, main, holder, accNo, embossName1, embossName2): present on most responses but not strictly guaranteed.

cardHash
string

128-char hex card hash.

cardKey
string

16-char card key (the same :id from the request).

expDate
string

Card expiry as MM/YYYY.

status
string (CardStatus)
Enum Description
ACTIVE

Card is open and can transact.

LOCKED

Cardholder- or admin-initiated lock. Reversible via unlock.

BLOCKED

Admin-initiated block. Reversible by an admin.

EXPIRED

Card has reached its expiry date.

CLOSED

Card is permanently closed.

ORDERED

Card has been ordered but not yet produced / activated.

INACTIVE

Card exists but is currently disabled (not in use).

RESTRICTED

Card is online-only (e.g. no ATM). Reversible.

Card lifecycle state as returned by IT Card.

statusCode
string

Raw card status code from the card-issuing platform (e.g. 00, BL, KZ).

kind
string
Enum: "DEBIT" "CREDIT" "PREPAID"

Card kind (form-factor family). There is no type field.

productCode
string

4-char product code (e.g. R004, DCT).

productDesc
string or null

Human-readable product description (e.g. RYVYL VISA BUSINESS DEBIT VTL).

main
boolean or null

true if this is the cardholder's primary card.

holder
string or null

Cardholder client code (e.g. RYVL-1720_1).

accNo
string or null

IBAN of the account that funds the card.

embossName1
string or null <= 26 characters

Embossed cardholder name (line 1).

embossName2
string or null <= 30 characters

Embossed company name (line 2).

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "data": {
    }
}

Temporary lock card

Temporarily locks the card (e.g. while the holder travels). Optional body.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Card cardKey (for example KDRYV0XXXXXXXXXX).

Request Body schema: application/json
optional
expDate
required
string^(0[1-9]|1[0-2])\/\d{4}$

Card expiration in MM/YYYY

reason
string

Audit reason (free-form)

Responses

Response Schema: application/json
object (CardActionResponse)

Response returned by every card-lifecycle endpoint that does not move the card to a new cardKey — i.e. lock, unlock, activate, temporary-lock-card, restrict, restrict-card-as-lost, restrict-card-as-stolen, restrict-card-as-closed, restrict-card-fraud, embossName, and resetPinTries.

No cardMask on this shape — use GET /api/partner/cards/{id} to fetch it.

Required: cardHash, cardKey, expDate, status, statusCode, kind, productCode. Optional (productDesc, main, holder, accNo, embossName1, embossName2): present on most responses but not strictly guaranteed.

cardHash
string

128-char hex card hash.

cardKey
string

16-char card key (the same :id from the request).

expDate
string

Card expiry as MM/YYYY.

status
string (CardStatus)
Enum Description
ACTIVE

Card is open and can transact.

LOCKED

Cardholder- or admin-initiated lock. Reversible via unlock.

BLOCKED

Admin-initiated block. Reversible by an admin.

EXPIRED

Card has reached its expiry date.

CLOSED

Card is permanently closed.

ORDERED

Card has been ordered but not yet produced / activated.

INACTIVE

Card exists but is currently disabled (not in use).

RESTRICTED

Card is online-only (e.g. no ATM). Reversible.

Card lifecycle state as returned by IT Card.

statusCode
string

Raw card status code from the card-issuing platform (e.g. 00, BL, KZ).

kind
string
Enum: "DEBIT" "CREDIT" "PREPAID"

Card kind (form-factor family). There is no type field.

productCode
string

4-char product code (e.g. R004, DCT).

productDesc
string or null

Human-readable product description (e.g. RYVYL VISA BUSINESS DEBIT VTL).

main
boolean or null

true if this is the cardholder's primary card.

holder
string or null

Cardholder client code (e.g. RYVL-1720_1).

accNo
string or null

IBAN of the account that funds the card.

embossName1
string or null <= 26 characters

Embossed cardholder name (line 1).

embossName2
string or null <= 30 characters

Embossed company name (line 2).

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "data": {
    }
}

Restrict card (generic)

Generic card restriction. Body is optional.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Card cardKey (for example KDRYV0XXXXXXXXXX).

Request Body schema: application/json
optional
expDate
string^(0[1-9]|1[0-2])\/\d{4}$
reason
string
description
string
cardLocation
string

Where the card was last seen

Responses

Response Schema: application/json
object (CardActionResponse)

Response returned by every card-lifecycle endpoint that does not move the card to a new cardKey — i.e. lock, unlock, activate, temporary-lock-card, restrict, restrict-card-as-lost, restrict-card-as-stolen, restrict-card-as-closed, restrict-card-fraud, embossName, and resetPinTries.

No cardMask on this shape — use GET /api/partner/cards/{id} to fetch it.

Required: cardHash, cardKey, expDate, status, statusCode, kind, productCode. Optional (productDesc, main, holder, accNo, embossName1, embossName2): present on most responses but not strictly guaranteed.

cardHash
string

128-char hex card hash.

cardKey
string

16-char card key (the same :id from the request).

expDate
string

Card expiry as MM/YYYY.

status
string (CardStatus)
Enum Description
ACTIVE

Card is open and can transact.

LOCKED

Cardholder- or admin-initiated lock. Reversible via unlock.

BLOCKED

Admin-initiated block. Reversible by an admin.

EXPIRED

Card has reached its expiry date.

CLOSED

Card is permanently closed.

ORDERED

Card has been ordered but not yet produced / activated.

INACTIVE

Card exists but is currently disabled (not in use).

RESTRICTED

Card is online-only (e.g. no ATM). Reversible.

Card lifecycle state as returned by IT Card.

statusCode
string

Raw card status code from the card-issuing platform (e.g. 00, BL, KZ).

kind
string
Enum: "DEBIT" "CREDIT" "PREPAID"

Card kind (form-factor family). There is no type field.

productCode
string

4-char product code (e.g. R004, DCT).

productDesc
string or null

Human-readable product description (e.g. RYVYL VISA BUSINESS DEBIT VTL).

main
boolean or null

true if this is the cardholder's primary card.

holder
string or null

Cardholder client code (e.g. RYVL-1720_1).

accNo
string or null

IBAN of the account that funds the card.

embossName1
string or null <= 26 characters

Embossed cardholder name (line 1).

embossName2
string or null <= 30 characters

Embossed company name (line 2).

Request samples

Content type
application/json
{
  • "expDate": "12/2030",
  • "reason": "custom",
  • "description": "Optional description"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Restrict card as lost

Restricts the card as lost. The card cannot be used; the holder must request a replacement. Body is optional.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Card cardKey (for example KDRYV0XXXXXXXXXX).

Request Body schema: application/json
optional
expDate
string^(0[1-9]|1[0-2])\/\d{4}$
reason
string
description
string
cardLocation
string

Where the card was last seen

Responses

Response Schema: application/json
object (CardActionResponse)

Response returned by every card-lifecycle endpoint that does not move the card to a new cardKey — i.e. lock, unlock, activate, temporary-lock-card, restrict, restrict-card-as-lost, restrict-card-as-stolen, restrict-card-as-closed, restrict-card-fraud, embossName, and resetPinTries.

No cardMask on this shape — use GET /api/partner/cards/{id} to fetch it.

Required: cardHash, cardKey, expDate, status, statusCode, kind, productCode. Optional (productDesc, main, holder, accNo, embossName1, embossName2): present on most responses but not strictly guaranteed.

cardHash
string

128-char hex card hash.

cardKey
string

16-char card key (the same :id from the request).

expDate
string

Card expiry as MM/YYYY.

status
string (CardStatus)
Enum Description
ACTIVE

Card is open and can transact.

LOCKED

Cardholder- or admin-initiated lock. Reversible via unlock.

BLOCKED

Admin-initiated block. Reversible by an admin.

EXPIRED

Card has reached its expiry date.

CLOSED

Card is permanently closed.

ORDERED

Card has been ordered but not yet produced / activated.

INACTIVE

Card exists but is currently disabled (not in use).

RESTRICTED

Card is online-only (e.g. no ATM). Reversible.

Card lifecycle state as returned by IT Card.

statusCode
string

Raw card status code from the card-issuing platform (e.g. 00, BL, KZ).

kind
string
Enum: "DEBIT" "CREDIT" "PREPAID"

Card kind (form-factor family). There is no type field.

productCode
string

4-char product code (e.g. R004, DCT).

productDesc
string or null

Human-readable product description (e.g. RYVYL VISA BUSINESS DEBIT VTL).

main
boolean or null

true if this is the cardholder's primary card.

holder
string or null

Cardholder client code (e.g. RYVL-1720_1).

accNo
string or null

IBAN of the account that funds the card.

embossName1
string or null <= 26 characters

Embossed cardholder name (line 1).

embossName2
string or null <= 30 characters

Embossed company name (line 2).

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "data": {
    }
}

Restrict card as stolen

Restricts the card as stolen. Body is optional.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Card cardKey (for example KDRYV0XXXXXXXXXX).

Request Body schema: application/json
optional
expDate
string^(0[1-9]|1[0-2])\/\d{4}$
reason
string
description
string
cardLocation
string

Where the card was last seen

Responses

Response Schema: application/json
object (CardActionResponse)

Response returned by every card-lifecycle endpoint that does not move the card to a new cardKey — i.e. lock, unlock, activate, temporary-lock-card, restrict, restrict-card-as-lost, restrict-card-as-stolen, restrict-card-as-closed, restrict-card-fraud, embossName, and resetPinTries.

No cardMask on this shape — use GET /api/partner/cards/{id} to fetch it.

Required: cardHash, cardKey, expDate, status, statusCode, kind, productCode. Optional (productDesc, main, holder, accNo, embossName1, embossName2): present on most responses but not strictly guaranteed.

cardHash
string

128-char hex card hash.

cardKey
string

16-char card key (the same :id from the request).

expDate
string

Card expiry as MM/YYYY.

status
string (CardStatus)
Enum Description
ACTIVE

Card is open and can transact.

LOCKED

Cardholder- or admin-initiated lock. Reversible via unlock.

BLOCKED

Admin-initiated block. Reversible by an admin.

EXPIRED

Card has reached its expiry date.

CLOSED

Card is permanently closed.

ORDERED

Card has been ordered but not yet produced / activated.

INACTIVE

Card exists but is currently disabled (not in use).

RESTRICTED

Card is online-only (e.g. no ATM). Reversible.

Card lifecycle state as returned by IT Card.

statusCode
string

Raw card status code from the card-issuing platform (e.g. 00, BL, KZ).

kind
string
Enum: "DEBIT" "CREDIT" "PREPAID"

Card kind (form-factor family). There is no type field.

productCode
string

4-char product code (e.g. R004, DCT).

productDesc
string or null

Human-readable product description (e.g. RYVYL VISA BUSINESS DEBIT VTL).

main
boolean or null

true if this is the cardholder's primary card.

holder
string or null

Cardholder client code (e.g. RYVL-1720_1).

accNo
string or null

IBAN of the account that funds the card.

embossName1
string or null <= 26 characters

Embossed cardholder name (line 1).

embossName2
string or null <= 30 characters

Embossed company name (line 2).

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "data": {
    }
}

Restrict card as closed

Restricts the card as closed. Body is optional.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Card cardKey (for example KDRYV0XXXXXXXXXX).

Request Body schema: application/json
optional
expDate
string^(0[1-9]|1[0-2])\/\d{4}$
reason
string
description
string
cardLocation
string

Where the card was last seen

Responses

Response Schema: application/json
object (CardActionResponse)

Response returned by every card-lifecycle endpoint that does not move the card to a new cardKey — i.e. lock, unlock, activate, temporary-lock-card, restrict, restrict-card-as-lost, restrict-card-as-stolen, restrict-card-as-closed, restrict-card-fraud, embossName, and resetPinTries.

No cardMask on this shape — use GET /api/partner/cards/{id} to fetch it.

Required: cardHash, cardKey, expDate, status, statusCode, kind, productCode. Optional (productDesc, main, holder, accNo, embossName1, embossName2): present on most responses but not strictly guaranteed.

cardHash
string

128-char hex card hash.

cardKey
string

16-char card key (the same :id from the request).

expDate
string

Card expiry as MM/YYYY.

status
string (CardStatus)
Enum Description
ACTIVE

Card is open and can transact.

LOCKED

Cardholder- or admin-initiated lock. Reversible via unlock.

BLOCKED

Admin-initiated block. Reversible by an admin.

EXPIRED

Card has reached its expiry date.

CLOSED

Card is permanently closed.

ORDERED

Card has been ordered but not yet produced / activated.

INACTIVE

Card exists but is currently disabled (not in use).

RESTRICTED

Card is online-only (e.g. no ATM). Reversible.

Card lifecycle state as returned by IT Card.

statusCode
string

Raw card status code from the card-issuing platform (e.g. 00, BL, KZ).

kind
string
Enum: "DEBIT" "CREDIT" "PREPAID"

Card kind (form-factor family). There is no type field.

productCode
string

4-char product code (e.g. R004, DCT).

productDesc
string or null

Human-readable product description (e.g. RYVYL VISA BUSINESS DEBIT VTL).

main
boolean or null

true if this is the cardholder's primary card.

holder
string or null

Cardholder client code (e.g. RYVL-1720_1).

accNo
string or null

IBAN of the account that funds the card.

embossName1
string or null <= 26 characters

Embossed cardholder name (line 1).

embossName2
string or null <= 30 characters

Embossed company name (line 2).

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "data": {
    }
}

Restrict card as fraud

Restricts the card as fraud. Body is optional.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Card cardKey (for example KDRYV0XXXXXXXXXX).

Request Body schema: application/json
optional
expDate
string^(0[1-9]|1[0-2])\/\d{4}$
reason
string
description
string
cardLocation
string

Where the card was last seen

Responses

Response Schema: application/json
object (CardActionResponse)

Response returned by every card-lifecycle endpoint that does not move the card to a new cardKey — i.e. lock, unlock, activate, temporary-lock-card, restrict, restrict-card-as-lost, restrict-card-as-stolen, restrict-card-as-closed, restrict-card-fraud, embossName, and resetPinTries.

No cardMask on this shape — use GET /api/partner/cards/{id} to fetch it.

Required: cardHash, cardKey, expDate, status, statusCode, kind, productCode. Optional (productDesc, main, holder, accNo, embossName1, embossName2): present on most responses but not strictly guaranteed.

cardHash
string

128-char hex card hash.

cardKey
string

16-char card key (the same :id from the request).

expDate
string

Card expiry as MM/YYYY.

status
string (CardStatus)
Enum Description
ACTIVE

Card is open and can transact.

LOCKED

Cardholder- or admin-initiated lock. Reversible via unlock.

BLOCKED

Admin-initiated block. Reversible by an admin.

EXPIRED

Card has reached its expiry date.

CLOSED

Card is permanently closed.

ORDERED

Card has been ordered but not yet produced / activated.

INACTIVE

Card exists but is currently disabled (not in use).

RESTRICTED

Card is online-only (e.g. no ATM). Reversible.

Card lifecycle state as returned by IT Card.

statusCode
string

Raw card status code from the card-issuing platform (e.g. 00, BL, KZ).

kind
string
Enum: "DEBIT" "CREDIT" "PREPAID"

Card kind (form-factor family). There is no type field.

productCode
string

4-char product code (e.g. R004, DCT).

productDesc
string or null

Human-readable product description (e.g. RYVYL VISA BUSINESS DEBIT VTL).

main
boolean or null

true if this is the cardholder's primary card.

holder
string or null

Cardholder client code (e.g. RYVL-1720_1).

accNo
string or null

IBAN of the account that funds the card.

embossName1
string or null <= 26 characters

Embossed cardholder name (line 1).

embossName2
string or null <= 30 characters

Embossed company name (line 2).

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "data": {
    }
}

Change emboss name

Updates the embossed name on the card. Note: spaces are not allowed in the emboss-name request.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Card cardKey (for example KDRYV0XXXXXXXXXX).

Request Body schema: application/json
required
embossName1
required
string <= 22 characters
embossName2
string <= 19 characters

Responses

Response Schema: application/json
object (CardActionResponse)

Response returned by every card-lifecycle endpoint that does not move the card to a new cardKey — i.e. lock, unlock, activate, temporary-lock-card, restrict, restrict-card-as-lost, restrict-card-as-stolen, restrict-card-as-closed, restrict-card-fraud, embossName, and resetPinTries.

No cardMask on this shape — use GET /api/partner/cards/{id} to fetch it.

Required: cardHash, cardKey, expDate, status, statusCode, kind, productCode. Optional (productDesc, main, holder, accNo, embossName1, embossName2): present on most responses but not strictly guaranteed.

cardHash
string

128-char hex card hash.

cardKey
string

16-char card key (the same :id from the request).

expDate
string

Card expiry as MM/YYYY.

status
string (CardStatus)
Enum Description
ACTIVE

Card is open and can transact.

LOCKED

Cardholder- or admin-initiated lock. Reversible via unlock.

BLOCKED

Admin-initiated block. Reversible by an admin.

EXPIRED

Card has reached its expiry date.

CLOSED

Card is permanently closed.

ORDERED

Card has been ordered but not yet produced / activated.

INACTIVE

Card exists but is currently disabled (not in use).

RESTRICTED

Card is online-only (e.g. no ATM). Reversible.

Card lifecycle state as returned by IT Card.

statusCode
string

Raw card status code from the card-issuing platform (e.g. 00, BL, KZ).

kind
string
Enum: "DEBIT" "CREDIT" "PREPAID"

Card kind (form-factor family). There is no type field.

productCode
string

4-char product code (e.g. R004, DCT).

productDesc
string or null

Human-readable product description (e.g. RYVYL VISA BUSINESS DEBIT VTL).

main
boolean or null

true if this is the cardholder's primary card.

holder
string or null

Cardholder client code (e.g. RYVL-1720_1).

accNo
string or null

IBAN of the account that funds the card.

embossName1
string or null <= 26 characters

Embossed cardholder name (line 1).

embossName2
string or null <= 30 characters

Embossed company name (line 2).

Request samples

Content type
application/json
{
  • "embossName1": "CASEY SAMPLE"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Replace card

Replaces the physical card. The returned response carries a new cardKey — store the new value because the old key is no longer valid for any subsequent operation on this card.

The response includes cardMask. If the upstream card-issuing platform is temporarily unavailable, cardMask may be null.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Card cardKey (for example KDRYV0XXXXXXXXXX).

Request Body schema: application/json
required
expDate
required
string^(0[1-9]|1[0-2])\/\d{4}$
reason
string
pinMailer
string

Postal pin-mailer reference

Responses

Response Schema: application/json
object (ReplaceCardResponse)

Body returned by replace-card and resign-card. These endpoints rotate the card to a new cardKey, so the response always carries the new key.

Carries every field of CardActionResponse plus cardMask. If the upstream card-issuing platform is temporarily unavailable, cardMask may be null.

cardHash
string

128-char hex card hash.

cardKey
string

16-char card key (the same :id from the request).

expDate
string

Card expiry as MM/YYYY.

status
string (CardStatus)
Enum Description
ACTIVE

Card is open and can transact.

LOCKED

Cardholder- or admin-initiated lock. Reversible via unlock.

BLOCKED

Admin-initiated block. Reversible by an admin.

EXPIRED

Card has reached its expiry date.

CLOSED

Card is permanently closed.

ORDERED

Card has been ordered but not yet produced / activated.

INACTIVE

Card exists but is currently disabled (not in use).

RESTRICTED

Card is online-only (e.g. no ATM). Reversible.

Card lifecycle state as returned by IT Card.

statusCode
string

Raw card status code from the card-issuing platform (e.g. 00, BL, KZ).

kind
string
Enum: "DEBIT" "CREDIT" "PREPAID"

Card kind (form-factor family). There is no type field.

productCode
string

4-char product code (e.g. R004, DCT).

productDesc
string or null

Human-readable product description (e.g. RYVYL VISA BUSINESS DEBIT VTL).

main
boolean or null

true if this is the cardholder's primary card.

holder
string or null

Cardholder client code (e.g. RYVL-1720_1).

accNo
string or null

IBAN of the account that funds the card.

embossName1
string or null <= 26 characters

Embossed cardholder name (line 1).

embossName2
string or null <= 30 characters

Embossed company name (line 2).

cardMask
string or null

Masked PAN of the new card (e.g. 446614******5015). May be null if the upstream platform is temporarily unavailable.

Request samples

Content type
application/json
{
  • "expDate": "06/2029"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Re-issue / resign card

Re-issues the card (e.g. PIN reissue, expiration). The returned response carries a new cardKey — store the new value because the old key is no longer valid for any subsequent operation on this card. The old card is closed.

The response includes cardMask. If the upstream card-issuing platform is temporarily unavailable, cardMask may be null.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Card cardKey (for example KDRYV0XXXXXXXXXX).

Request Body schema: application/json
required
expDate
required
string^(0[1-9]|1[0-2])\/\d{4}$
reason
string
pinMailer
string

Postal pin-mailer reference

Responses

Response Schema: application/json
object (ReplaceCardResponse)

Body returned by replace-card and resign-card. These endpoints rotate the card to a new cardKey, so the response always carries the new key.

Carries every field of CardActionResponse plus cardMask. If the upstream card-issuing platform is temporarily unavailable, cardMask may be null.

cardHash
string

128-char hex card hash.

cardKey
string

16-char card key (the same :id from the request).

expDate
string

Card expiry as MM/YYYY.

status
string (CardStatus)
Enum Description
ACTIVE

Card is open and can transact.

LOCKED

Cardholder- or admin-initiated lock. Reversible via unlock.

BLOCKED

Admin-initiated block. Reversible by an admin.

EXPIRED

Card has reached its expiry date.

CLOSED

Card is permanently closed.

ORDERED

Card has been ordered but not yet produced / activated.

INACTIVE

Card exists but is currently disabled (not in use).

RESTRICTED

Card is online-only (e.g. no ATM). Reversible.

Card lifecycle state as returned by IT Card.

statusCode
string

Raw card status code from the card-issuing platform (e.g. 00, BL, KZ).

kind
string
Enum: "DEBIT" "CREDIT" "PREPAID"

Card kind (form-factor family). There is no type field.

productCode
string

4-char product code (e.g. R004, DCT).

productDesc
string or null

Human-readable product description (e.g. RYVYL VISA BUSINESS DEBIT VTL).

main
boolean or null

true if this is the cardholder's primary card.

holder
string or null

Cardholder client code (e.g. RYVL-1720_1).

accNo
string or null

IBAN of the account that funds the card.

embossName1
string or null <= 26 characters

Embossed cardholder name (line 1).

embossName2
string or null <= 30 characters

Embossed company name (line 2).

cardMask
string or null

Masked PAN of the new card (e.g. 446614******5015). May be null if the upstream platform is temporarily unavailable.

Request samples

Content type
application/json
{
  • "reason": "Test resign"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get card CVV

Returns the CVV2 for the card. Sensitive — never log this response. The successful response contains an encrypted envelope for the partner's registered encryption public key. The partner decrypts it with its private key. No plaintext CVV is returned.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Card cardKey (for example KDRYV0XXXXXXXXXX).

query Parameters
expDate
required
string^(0[1-9]|1[0-2])\/\d{4}$

Card expiration in MM/YYYY format

Responses

Response Schema: application/json
required
object (EncryptedCardData)

Minimal encrypted envelope for a single sensitive card value.

Cipher: ECDH-ES on curve secp521r1 (P-521), HKDF-SHA256, AES-256-GCM.

v
required
integer
Value: 1
p
required
string
Enum: "cvv2" "pan"
c
required
string

Card cardKey the encrypted value belongs to.

k
required
string

Partner encryption keyId.

e
required
string

Ephemeral server P-521 public key.

iv
required
string

12-byte AES-GCM nonce, base64url.

ct
required
string

AES-256-GCM ciphertext, base64url.

t
required
string

AES-GCM authentication tag, base64url.

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get full card number (PAN)

Returns the full PAN for the card. Highly sensitive — never log this response. The successful response contains an encrypted envelope for the partner's registered encryption public key. The partner decrypts it with its private key. No plaintext PAN is returned.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Card cardKey (for example KDRYV0XXXXXXXXXX).

query Parameters
expDate
required
string^(0[1-9]|1[0-2])\/\d{4}$

Card expiration in MM/YYYY format

Responses

Response Schema: application/json
required
object (EncryptedCardData)

Minimal encrypted envelope for a single sensitive card value.

Cipher: ECDH-ES on curve secp521r1 (P-521), HKDF-SHA256, AES-256-GCM.

v
required
integer
Value: 1
p
required
string
Enum: "cvv2" "pan"
c
required
string

Card cardKey the encrypted value belongs to.

k
required
string

Partner encryption keyId.

e
required
string

Ephemeral server P-521 public key.

iv
required
string

12-byte AES-GCM nonce, base64url.

ct
required
string

AES-256-GCM ciphertext, base64url.

t
required
string

AES-GCM authentication tag, base64url.

Response samples

Content type
application/json
{
  • "data": {
    }
}

Set 3DS answer

Updates the 3-D Secure answer configured on the card.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Card cardKey (for example KDRYV0XXXXXXXXXX).

header Parameters
Idempotency-Key
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

Optional idempotency key to ensure safe retries for non-GET requests.

When provided, the API remembers your request and returns the exact same result if the same key is sent within 60 seconds. This protects against duplicate operations in case of network timeouts or accidental retries.

Recommended: Use a UUID v4 for each logical operation.

Response headers:

  • Same key + same request → original response + X-Idempotency-Replay: true
  • Same key + different request → 409 Conflict
  • Request still processing → 202 Accepted
Request Body schema: application/json
required
answer
required
string <= 200 characters

Responses

Response Schema: application/json
message
string

Human-readable success message.

Request samples

Content type
application/json
{
  • "answer": "my-secure-answer"
}

Response samples

Content type
application/json
{
  • "message": "Success"
}

Change 3DS phone number

Updates the phone number used to deliver the 3-D Secure OTP.

Which phone number is used for 3-D Secure? The cardholder record carries two phone fields:

  • authPhoneNumber — the dedicated phone for 3-D Secure OTP delivery
  • phoneNumber — the general contact phone

At 3-D Secure time we use authPhoneNumber if it is set; if it is empty, we fall back to phoneNumber. The value you POST in newPhoneNumber on this endpoint becomes the new authPhoneNumber.

Response shape. The success path returns exactly { "success": true }. The warnings field is only present when a downstream sync silently failed — it is omitted entirely on the all-clean path, never returned as an empty array.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Card cardKey (for example KDRYV0XXXXXXXXXX).

Request Body schema: application/json
required
newPhoneNumber
required
string <= 16 characters ^\+?\d{4,16}$

New 3-D Secure phone number. Stored as the cardholder's authPhoneNumber. 4–16 characters, digits only, optional leading +.

Responses

Response Schema: application/json
success
boolean
warnings
Array of strings

Present only when at least one downstream sync failed. Each entry is a human-readable description of one failed downstream store. Omitted entirely on the success path.

Request samples

Content type
application/json
{
  • "newPhoneNumber": "+10000000000"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "warnings": [
    ]
}

Reset PIN tries

Resets the cardholder's PIN-attempt counter.

The response carries the same CardActionResponse shape as the other card-lifecycle endpoints (lock, unlock, activate, restrict, etc.) — a flat card-action row, not the full card details.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Card cardKey (for example KDRYV0XXXXXXXXXX).

Responses

Response Schema: application/json
object (CardActionResponse)

Response returned by every card-lifecycle endpoint that does not move the card to a new cardKey — i.e. lock, unlock, activate, temporary-lock-card, restrict, restrict-card-as-lost, restrict-card-as-stolen, restrict-card-as-closed, restrict-card-fraud, embossName, and resetPinTries.

No cardMask on this shape — use GET /api/partner/cards/{id} to fetch it.

Required: cardHash, cardKey, expDate, status, statusCode, kind, productCode. Optional (productDesc, main, holder, accNo, embossName1, embossName2): present on most responses but not strictly guaranteed.

cardHash
string

128-char hex card hash.

cardKey
string

16-char card key (the same :id from the request).

expDate
string

Card expiry as MM/YYYY.

status
string (CardStatus)
Enum Description
ACTIVE

Card is open and can transact.

LOCKED

Cardholder- or admin-initiated lock. Reversible via unlock.

BLOCKED

Admin-initiated block. Reversible by an admin.

EXPIRED

Card has reached its expiry date.

CLOSED

Card is permanently closed.

ORDERED

Card has been ordered but not yet produced / activated.

INACTIVE

Card exists but is currently disabled (not in use).

RESTRICTED

Card is online-only (e.g. no ATM). Reversible.

Card lifecycle state as returned by IT Card.

statusCode
string

Raw card status code from the card-issuing platform (e.g. 00, BL, KZ).

kind
string
Enum: "DEBIT" "CREDIT" "PREPAID"

Card kind (form-factor family). There is no type field.

productCode
string

4-char product code (e.g. R004, DCT).

productDesc
string or null

Human-readable product description (e.g. RYVYL VISA BUSINESS DEBIT VTL).

main
boolean or null

true if this is the cardholder's primary card.

holder
string or null

Cardholder client code (e.g. RYVL-1720_1).

accNo
string or null

IBAN of the account that funds the card.

embossName1
string or null <= 26 characters

Embossed cardholder name (line 1).

embossName2
string or null <= 30 characters

Embossed company name (line 2).

Response samples

Content type
application/json
{
  • "data": {
    }
}

Change PIN

Changes the card PIN. newPin is the raw 4–6 digit PIN; it is encrypted before being sent to the card-issuing platform.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Card cardKey (for example KDRYV0XXXXXXXXXX).

Request Body schema: application/json
required
newPin
required
string [ 4 .. 6 ] characters ^\d{4,6}$

New PIN, raw 4–6 digits.

Responses

Response Schema: application/json
cardHash
string

128-char hex card hash.

cardKey
string

16-char card key. The user-facing identifier used as :id in /api/partner/cards/{id} paths.

cardUuid
string or null

Card-issuing platform internal UUID.

cardMask
string

Masked card number (e.g. 446614******9605).

expDate
string

Card expiry as MM/YYYY.

issueDate
string <date>

Card issue date as yyyy-MM-dd.

status
string (CardStatus)
Enum Description
ACTIVE

Card is open and can transact.

LOCKED

Cardholder- or admin-initiated lock. Reversible via unlock.

BLOCKED

Admin-initiated block. Reversible by an admin.

EXPIRED

Card has reached its expiry date.

CLOSED

Card is permanently closed.

ORDERED

Card has been ordered but not yet produced / activated.

INACTIVE

Card exists but is currently disabled (not in use).

RESTRICTED

Card is online-only (e.g. no ATM). Reversible.

Card lifecycle state as returned by IT Card.

statusCode
string

Raw card status code from the card-issuing platform (e.g. 00, S1, L1).

terminating
boolean

true while the card is mid-termination.

productCode
string

4-char product code (e.g. R004).

productDesc
string or null

Human-readable product name (e.g. RYVYL VISA BUSINESS DEBIT VTL).

holder
string

Card holder client code (e.g. RYVL-1720_1).

Array of objects (PartnerCardAccount)

One or more accounts the card is linked to.

embossName1
string or null

Embossed cardholder name (line 1, max 22 chars).

embossName2
string or null

Embossed company name (line 2, max 19 chars).

source
string

Card source. Common values: NEW, RENEW, REPLACE, RESIGN.

kind
string
Enum: "DEBIT" "CREDIT" "PREPAID"

Card kind.

main
boolean

true for the cardholder's primary card.

Array of objects (PartnerCardLimit)

Per-card limit rows.

visual
string

Visual code (usually equal to productCode).

visualDesc
string or null

Human-readable visual description.

tokenized
boolean

true if the card has been tokenized (e.g. for Apple/Google Pay).

object (PartnerCardDelivery)

Card delivery metadata. Only deliveryType is reliably present — branch fields are populated only for branch-pickup deliveries.

contactless
boolean

true if contactless transactions are enabled.

cardTechnologyMode
string

Card technology mode. Common values: VIRTUAL, PHYSICAL, DUAL.

creationDate
string <date>

Card creation date as yyyy-MM-dd.

creationUser
string or null

Username/operator that created the card.

oldPlastic
string or null

Previous card plastic reference. Only set after a replace/resign.

autoRenewal
boolean

true if the card auto-renews on expiry.

saleChannelCode
string or null

3-char sale channel code.

Request samples

Content type
application/json
{
  • "newPin": "000000"
}

Response samples

Content type
application/json
{
  • "cardHash": "string",
  • "cardKey": "string",
  • "cardUuid": "string",
  • "cardMask": "string",
  • "expDate": "string",
  • "issueDate": "2019-08-24",
  • "status": "ACTIVE",
  • "statusCode": "string",
  • "terminating": true,
  • "productCode": "string",
  • "productDesc": "string",
  • "holder": "string",
  • "accounts": [
    ],
  • "embossName1": "string",
  • "embossName2": "string",
  • "source": "string",
  • "kind": "DEBIT",
  • "main": true,
  • "limits": [
    ],
  • "visual": "string",
  • "visualDesc": "string",
  • "tokenized": true,
  • "delivery": {
    },
  • "contactless": true,
  • "cardTechnologyMode": "string",
  • "creationDate": "2019-08-24",
  • "creationUser": "string",
  • "oldPlastic": "string",
  • "autoRenewal": true,
  • "saleChannelCode": "string"
}

Authorize cardholder

Authorizes a cardholder action. Requires the holder's pin (raw 4–6 digits).

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Card cardKey (for example KDRYV0XXXXXXXXXX).

Request Body schema: application/json
required
pin
required
string [ 4 .. 6 ] characters ^\d{4,6}$

Raw 4–6 digit PIN

Responses

Response Schema: application/json
cardHash
string

128-char hex card hash.

cardKey
string

16-char card key. The user-facing identifier used as :id in /api/partner/cards/{id} paths.

cardUuid
string or null

Card-issuing platform internal UUID.

cardMask
string

Masked card number (e.g. 446614******9605).

expDate
string

Card expiry as MM/YYYY.

issueDate
string <date>

Card issue date as yyyy-MM-dd.

status
string (CardStatus)
Enum Description
ACTIVE

Card is open and can transact.

LOCKED

Cardholder- or admin-initiated lock. Reversible via unlock.

BLOCKED

Admin-initiated block. Reversible by an admin.

EXPIRED

Card has reached its expiry date.

CLOSED

Card is permanently closed.

ORDERED

Card has been ordered but not yet produced / activated.

INACTIVE

Card exists but is currently disabled (not in use).

RESTRICTED

Card is online-only (e.g. no ATM). Reversible.

Card lifecycle state as returned by IT Card.

statusCode
string

Raw card status code from the card-issuing platform (e.g. 00, S1, L1).

terminating
boolean

true while the card is mid-termination.

productCode
string

4-char product code (e.g. R004).

productDesc
string or null

Human-readable product name (e.g. RYVYL VISA BUSINESS DEBIT VTL).

holder
string

Card holder client code (e.g. RYVL-1720_1).

Array of objects (PartnerCardAccount)

One or more accounts the card is linked to.

embossName1
string or null

Embossed cardholder name (line 1, max 22 chars).

embossName2
string or null

Embossed company name (line 2, max 19 chars).

source
string

Card source. Common values: NEW, RENEW, REPLACE, RESIGN.

kind
string
Enum: "DEBIT" "CREDIT" "PREPAID"

Card kind.

main
boolean

true for the cardholder's primary card.

Array of objects (PartnerCardLimit)

Per-card limit rows.

visual
string

Visual code (usually equal to productCode).

visualDesc
string or null

Human-readable visual description.

tokenized
boolean

true if the card has been tokenized (e.g. for Apple/Google Pay).

object (PartnerCardDelivery)

Card delivery metadata. Only deliveryType is reliably present — branch fields are populated only for branch-pickup deliveries.

contactless
boolean

true if contactless transactions are enabled.

cardTechnologyMode
string

Card technology mode. Common values: VIRTUAL, PHYSICAL, DUAL.

creationDate
string <date>

Card creation date as yyyy-MM-dd.

creationUser
string or null

Username/operator that created the card.

oldPlastic
string or null

Previous card plastic reference. Only set after a replace/resign.

autoRenewal
boolean

true if the card auto-renews on expiry.

saleChannelCode
string or null

3-char sale channel code.

Request samples

Content type
application/json
{
  • "pin": "000000"
}

Response samples

Content type
application/json
{
  • "cardHash": "string",
  • "cardKey": "string",
  • "cardUuid": "string",
  • "cardMask": "string",
  • "expDate": "string",
  • "issueDate": "2019-08-24",
  • "status": "ACTIVE",
  • "statusCode": "string",
  • "terminating": true,
  • "productCode": "string",
  • "productDesc": "string",
  • "holder": "string",
  • "accounts": [
    ],
  • "embossName1": "string",
  • "embossName2": "string",
  • "source": "string",
  • "kind": "DEBIT",
  • "main": true,
  • "limits": [
    ],
  • "visual": "string",
  • "visualDesc": "string",
  • "tokenized": true,
  • "delivery": {
    },
  • "contactless": true,
  • "cardTechnologyMode": "string",
  • "creationDate": "2019-08-24",
  • "creationUser": "string",
  • "oldPlastic": "string",
  • "autoRenewal": true,
  • "saleChannelCode": "string"
}

Get all card limits

Returns every spending limit for the card.

Use these fields to decide what you can set later with PATCH:

  • value — current limit on the card
  • approvalThreshold — values at or below this apply immediately (no approval)
  • max — highest value you may request (when present). Values above max are rejected with 400
  • pendingValue — included only when an in-flight change differs from value

If a limit has no finite cap, max / approvalThreshold may be omitted.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Card cardKey (for example KDRYV0XXXXXXXXXX).

Responses

Response Schema: application/json
Array of objects (CardLimit)
cardType
string
Enum: "VIRTUAL" "PHYSICAL"
limitChangeFee
number <double>

Fee that may apply when a limit change requires approval.

Response samples

Content type
application/json
{
  • "limits": [
    ],
  • "cardType": "VIRTUAL",
  • "limitChangeFee": 0.1
}

Patch card limits

Updates one or more card limits in a single call. Each item needs a concrete name (a CardLimitType) and a non-negative value.

First call GET /cards/{id}/limits and use approvalThreshold and max from that response.

For each requested value:

  • Above max → rejected with 400.
  • Above approvalThreshold, but at or below max → the whole batch needs approval. Nothing changes on the card yet. Response is 201 with pendingApproval: true and a taskId. A new batch cancels any older pending request for the same card.
  • At or below approvalThreshold → applied immediately (200).
Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Card cardKey (for example KDRYV0XXXXXXXXXX).

header Parameters
Idempotency-Key
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

Optional idempotency key to ensure safe retries for non-GET requests.

When provided, the API remembers your request and returns the exact same result if the same key is sent within 60 seconds. This protects against duplicate operations in case of network timeouts or accidental retries.

Recommended: Use a UUID v4 for each logical operation.

Response headers:

  • Same key + same request → original response + X-Idempotency-Replay: true
  • Same key + different request → 409 Conflict
  • Request still processing → 202 Accepted
Request Body schema: application/json
required
Array (non-empty)
name
required
string (CardLimitType)
Enum: "POS_PUR_LMT" "ATM_CCA_LMT" "CNP_AMT_LMT" "MONTH_POS_PUR_LMT" "MONTH_ATM_CCA_LMT" "MONTH_AMT_CNP_LMT" "ATM_USE_LMT" "POS_USE_LMT" "MONTH_TRANS_AMT_LMT" "PERIOD_TRANS_AMT" "ECOMM_AMT_LMT"

Which limit types are configurable depends on the card's product — not every product configures every type. For a full list of limit types, see Limit types.

value
required
number <double> >= 0

Responses

Response Schema: application/json
success
boolean
pendingApproval
boolean
Array of objects (CardLimit)
Response Schema: application/json
pendingApproval
boolean
taskId
string

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "success": true,
  • "pendingApproval": false,
  • "data": [
    ]
}

Get available limit

Returns how much is still left for one limit before it is hit. Example: for POS_PUR_LMT, how much of today's purchase limit is still unused.

Response fields:

  • name — limit type
  • value — current configured limit
  • available — remaining amount or count
Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Card cardKey (for example KDRYV0XXXXXXXXXX).

limitName
required
string (CardLimitType)
Enum: "POS_PUR_LMT" "ATM_CCA_LMT" "CNP_AMT_LMT" "MONTH_POS_PUR_LMT" "MONTH_ATM_CCA_LMT" "MONTH_AMT_CNP_LMT" "ATM_USE_LMT" "POS_USE_LMT" "MONTH_TRANS_AMT_LMT" "PERIOD_TRANS_AMT" "ECOMM_AMT_LMT"

A CardLimitType code, e.g. POS_PUR_LMT. See Limit types.

Responses

Response Schema: application/json
name
string (CardLimitType)
Enum: "POS_PUR_LMT" "ATM_CCA_LMT" "CNP_AMT_LMT" "MONTH_POS_PUR_LMT" "MONTH_ATM_CCA_LMT" "MONTH_AMT_CNP_LMT" "ATM_USE_LMT" "POS_USE_LMT" "MONTH_TRANS_AMT_LMT" "PERIOD_TRANS_AMT" "ECOMM_AMT_LMT"

Which limit types are configurable depends on the card's product — not every product configures every type. For a full list of limit types, see Limit types.

value
number <double>
available
number <double>

Remaining amount (or count) before this limit is hit.

Response samples

Content type
application/json
{
  • "name": "POS_PUR_LMT",
  • "value": 0.1,
  • "available": 0.1
}

Get what a prepaid card can be loaded from

Returns the card with its balance, its owner, and the main accounts the card can be loaded from, with their balances. Use one of sourceAccounts[].id as sourceAccountId to load the card.

The money always comes from the card's owner: the individual for a card of an individual, the company for a card of a B2B cardholder.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Card cardKey (for example KDRYV0XXXXXXXXXX).

Responses

Response Schema: application/json
object
object
object
Array of objects (PrepaidCardLoadSourceAccount)
currency
string
minAmount
number
hasOpenLoad
boolean

A load of this card is not finished yet; a new one is refused until it is.

Response samples

Content type
application/json
{
  • "data": {
    }
}

List the loads of a prepaid card

The loads of the card, newest first.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Card cardKey (for example KDRYV0XXXXXXXXXX).

query Parameters
page
integer >= 1
Default: 1
limit
integer [ 1 .. 50 ]
Default: 10

Responses

Response Schema: application/json
Array of objects (PrepaidCardLoad)
object

Response samples

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

Load a prepaid card

Moves money from one of the owner's main accounts to the prepaid card.

The answer is 201 with the load. Its status is usually SUBMITTED: the bank accepted the payment and books it within a few seconds. Ask for the load with GET /cards/{id}/prepaid/loads/{loadId} until status is SUCCESS or FAILED.

UNCONFIRMED means the bank did not answer: the money may or may not have moved. PayNovus checks it. Do not load the card again until the load is finished - a new load of the card is refused (409) while one is not finished.

idempotencyKey is required: generate a new one for each load. A request with a key you already used is refused with 409 and code LOAD_ALREADY_EXISTS, and nothing is paid again. When that load is of the same card, its loadId is in the answer. Keys are yours alone: a key used by someone else does not conflict.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Card cardKey (for example KDRYV0XXXXXXXXXX).

Request Body schema: application/json
required
sourceAccountId
required
string

One of sourceAccounts[].id from the load options.

required
string or number

At most two decimals, dot separator. Between 0.01 and 1000000.

idempotencyKey
required
string

A new key for each load, e.g. a UUID. Checked against your own loads only.

Responses

Response Schema: application/json
object (PrepaidCardLoad)
id
string
cardKey
string
amount
number
currency
string
status
string (PrepaidCardLoadStatus)
Enum: "PENDING" "SUBMITTED" "UNCONFIRMED" "SUCCESS" "FAILED"

SUBMITTED: accepted by the bank, being booked. UNCONFIRMED: the bank did not answer, PayNovus checks it. SUCCESS and FAILED are final.

message
string or null

Why a load failed or is not confirmed yet.

sourceIban
string
createdAt
string <date-time>
updatedAt
string <date-time>
completedAt
string or null <date-time>

Request samples

Content type
application/json
{
  • "sourceAccountId": "6836df4c98653594cae54d80",
  • "amount": "25.00",
  • "idempotencyKey": "3f6c2a1e-9b7d-4c1a-8e2f-5d4b3a2c1e0f"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get one load of a prepaid card

Returns one load of the card. A SUBMITTED load is checked with the bank when you ask, so ask every few seconds until status is SUCCESS or FAILED. A load of another card is a 404.

Authorizations:
JWTBearerAuth
path Parameters
id
required
string

Card cardKey (for example KDRYV0XXXXXXXXXX).

loadId
required
string

The id of the load.

Responses

Response Schema: application/json
object (PrepaidCardLoad)
id
string
cardKey
string
amount
number
currency
string
status
string (PrepaidCardLoadStatus)
Enum: "PENDING" "SUBMITTED" "UNCONFIRMED" "SUCCESS" "FAILED"

SUBMITTED: accepted by the bank, being booked. UNCONFIRMED: the bank did not answer, PayNovus checks it. SUCCESS and FAILED are final.

message
string or null

Why a load failed or is not confirmed yet.

sourceIban
string
createdAt
string <date-time>
updatedAt
string <date-time>
completedAt
string or null <date-time>

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get physical card hold limit

Returns the maximum number of physical cards a single account may hold at any time. The cap is platform-wide, not per-card, so the endpoint is not scoped to a :id.

Use this to decide whether a new physical card can be issued for an account.

Authorizations:
JWTBearerAuth

Responses

Response Schema: application/json
object
limit
string

Maximum number of cards an account may hold. Forwarded as a string; parse with parseInt(limit, 10) to use numerically.

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get virtual card hold limit

Returns the maximum number of virtual cards a single account may hold at any time. The cap is platform-wide, not per-card, so the endpoint is not scoped to a :id.

Use this to decide whether a new virtual card can be issued for an account.

Authorizations:
JWTBearerAuth

Responses

Response Schema: application/json
object
limit
string

Maximum number of cards an account may hold. Forwarded as a string; parse with parseInt(limit, 10) to use numerically.

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get virtual card issuance quota (partner default)

Pre-issuance check for the rolling virtual-card issuance cap.

Lets a partner surface a "you're approaching your virtual card limit" warning in their own UI before opening the issuance flow, instead of discovering the cap only when the issuance call fails with 429.

Read-only. A skipped or stale check can never let an extra card through — the authoritative block lives in the issuance path, and both the pre-check and the issuance call evaluate the same quota.

When no cardholderId is supplied (neither path segment nor query string), the partner's first direct individual onboarding is used. A partner with no direct individuals gets 404 and must call the {cardholderId} variant for B2B cardholders.

Scope: applies to non-B2B cardholders only (partner-owned individuals). For B2B cardholders the response returns applies: false with a neutral non-blocking quota — issuance for B2B cardholders is governed by the per-account concurrent cap (GET /cards/hold-limits/virtual), not the rolling cap.

B2B cardholder behavior: if the quota does not apply to the resolved cardholder, the response is always applies: false, status: 'OK', used: 0, with remaining = limit and nextSlotFreesAt: null. The quota object is still returned (never omitted) so the partner client never has to branch on scope — any code that reads data.status === 'LIMIT_EXCEEDED' simply never fires for B2B cardholders.

Authorizations:
JWTBearerAuth
query Parameters
cardholderId
string

Optional cardholder identifier. When supplied, must belong to the calling partner — either directly (a partner-owned individual) or hosted under one of the partner's B2B tenants.

Equivalent to the :cardholderId path-segment variant on /cards/virtual-card-quota/{cardholderId} — both URL shapes are accepted; the path segment wins when both are supplied. Omit to resolve the partner's default (first direct individual).

Responses

Response Schema: application/json
success
boolean
object (VirtualCardWindowQuota)

Rolling-window virtual-card issuance decision for one cardholder. See VirtualCardQuotaResponse for the wrapping envelope.

When applies: false (B2B cardholders): every other field is still populated with a neutral, non-blocking result (status: 'OK', used: 0, remaining: limit, nextSlotFreesAt: null). The rolling cap is a per-individual gate and does not govern B2B cardholders; their issuance is governed instead by the per-account concurrent cap (GET /cards/hold-limits/virtual). The response is still returned (never omitted) so the partner client never has to branch on scope.

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get virtual card issuance quota for a specific cardholder

Pre-issuance check for the rolling virtual-card issuance cap on a specific cardholder.

The cardholder must be accessible to the calling partner:

  • a direct individual onboarding owned by the partner, or
  • a B2B cardholder hosted by one of the partner's B2B tenants.

Ownership-mismatch returns 404 Not Found with no further detail — identical whether the cardholder does not exist or belongs to another partner (no enumeration).

Read-only. A skipped or stale check can never let an extra card through — the authoritative block lives in the issuance path, and both the pre-check and the issuance call evaluate the same quota.

Scope: applies to non-B2B cardholders only (partner-owned individuals and direct individuals). For B2B cardholders the response returns applies: false with a neutral non-blocking quota — issuance for B2B cardholders is governed by the per-account concurrent cap (GET /cards/hold-limits/virtual), not the rolling cap.

B2B cardholder behavior: if the quota does not apply to the resolved cardholder, the response is always applies: false, status: 'OK', used: 0, with remaining = limit and nextSlotFreesAt: null. The quota object is still returned (never omitted) so the partner client never has to branch on scope — any code that reads data.status === 'LIMIT_EXCEEDED' simply never fires for B2B cardholders, and any code that reads data.used sees 0 instead of a misleading real count.

Status field guide:

status Meaning
OK Under the warning band — proceed silently.
WARNING_THRESHOLD_REACHED Still allowed, but the cardholder is close to the cap. Tell them.
LIMIT_EXCEEDED Cap reached; issuance will be blocked with 429.
Authorizations:
JWTBearerAuth
path Parameters
cardholderId
required
string

Cardholder identifier. Must belong to the calling partner — either directly (a partner-owned individual) or hosted under one of the partner's B2B tenants.

Equivalent to ?cardholderId=<id> on /cards/virtual-card-quota — the path segment wins when both are supplied.

Responses

Response Schema: application/json
success
boolean
object (VirtualCardWindowQuota)

Rolling-window virtual-card issuance decision for one cardholder. See VirtualCardQuotaResponse for the wrapping envelope.

When applies: false (B2B cardholders): every other field is still populated with a neutral, non-blocking result (status: 'OK', used: 0, remaining: limit, nextSlotFreesAt: null). The rolling cap is a per-individual gate and does not govern B2B cardholders; their issuance is governed instead by the per-account concurrent cap (GET /cards/hold-limits/virtual). The response is still returned (never omitted) so the partner client never has to branch on scope.

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Fees & Delivery

Fee and delivery-method lookups. The issuing/delivery fee endpoints validate the request payload before returning a quote.

List delivery methods by country

Returns PocztaPost + DHL delivery methods available for the given country. The match is case-insensitive on the full country name stored in the Country column of the source Excel upload (e.g. Bulgaria, BULGARIA, bulgaria all match the same row). Both collections are queried and their results merged in one response — there is no pagination.

The response is wrapped under data. The payload is dynamic: each records[] entry carries whatever columns the original Excel template held (delivery times, weight tiers, zone names, prices, etc.), in addition to upload-metadata fields prefixed with _.

Authorizations:
JWTBearerAuth
query Parameters
country
required
string
Example: country=Bulgaria

Full country name to look up (case-insensitive). Matched against the Country field stored on each row, e.g. Bulgaria, Poland, Germany. Not an ISO 3166-1 code.

Responses

Response Schema: application/json
object (DeliveryMethodsResponse)

Response body returned by GET /api/partner/fees/delivery-methods. The endpoint always nests the result under data — there is no top-level success flag.

success
boolean

Always true on success.

country
string

The country name echoed back from the request. This is the raw value of the country query parameter, not a normalized form.

object (PolishPostMethods)

PocztaPost (Polish Post) delivery methods matching the requested country.

object (DHLMethods)

DHL delivery methods matching the requested country.

totalCount
integer

Sum of polishPost.count and dhl.count.

Response samples

Content type
application/json
{
  • "data": {
    }
}

Check card issuing fee

Returns the fee for issuing a card. The endpoint looks up the fee by CustomerType + ProductType (and optionally cardKey / clientId / iban for narrowing).

Authorizations:
JWTBearerAuth
Request Body schema: application/json
required
CustomerType
required
string
Enum: "Consumer Debit" "Business Debit" "Consumer Prepaid" "Business Prepaid"
ProductType
required
string
Enum: "R001" "R002" "R003" "R004" "R005" "R006"
cardKey
string

Optional — card cardKey to narrow the fee lookup.

clientId
string

Optional — cardholder clientCode to narrow the fee lookup.

iban
string

Optional — account IBAN to narrow the fee lookup.

Responses

Response Schema: application/json
_id
string

Fee record _id.

deletedAt
string or null <date-time>

Soft-delete timestamp, null for active fee records.

GLAccountName
string

GL account name in the accounting system (e.g. Card Issuing Fees).

feeCode
string

Fee code (e.g. ISS1, DLV1).

operationType
string

Operation type this fee applies to (e.g. Card Issuing Fee, Card Delivery Fee).

customerType
string

Customer type this fee applies to (e.g. Consumer Debit).

productType
string

Product type this fee applies to (e.g. R001).

trigger
string

What triggers the fee (e.g. API Call).

loopOnCard
boolean

Whether the fee applies once per card or per transaction.

displayDescriptor
string

Human-readable descriptor shown in statements and admin UIs.

type
string

Fee class (e.g. Non Transactional).

currency
string

ISO 4217 currency code (e.g. EUR).

fixedFee
number <double>

Flat fee amount in currency.

percentageFee
number <double>

Percentage-based fee component, when applicable.

fxFixedFee
number <double>

Flat fee applied to FX transactions.

fxPercentageFee
number <double>

Percentage-based fee applied to FX transactions.

object (FeeSpecialCondition)

Special-condition block present on delivery-fee responses (and some issuing-fee responses). All keys are optional and reflect provider-specific overrides.

createdAt
string <date-time>
updatedAt
string <date-time>
__v
integer

Internal document version key.

property name*
additional property
any

Request samples

Content type
application/json
{
  • "CustomerType": "Consumer Debit",
  • "ProductType": "R001"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "deletedAt": "2019-08-24T14:15:22Z",
  • "GLAccountName": "string",
  • "feeCode": "string",
  • "operationType": "string",
  • "customerType": "string",
  • "productType": "string",
  • "trigger": "string",
  • "loopOnCard": true,
  • "displayDescriptor": "string",
  • "type": "string",
  • "currency": "string",
  • "fixedFee": 0.1,
  • "percentageFee": 0.1,
  • "fxFixedFee": 0.1,
  • "fxPercentageFee": 0.1,
  • "specialCondition": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "__v": 0
}

Check card delivery fee

Returns the fee for delivering a card. The endpoint looks up the fee by CustomerType + ProductType (and optionally cardKey / clientId / iban for narrowing).

Authorizations:
JWTBearerAuth
Request Body schema: application/json
required
CustomerType
required
string
Enum: "Consumer Debit" "Business Debit" "Consumer Prepaid" "Business Prepaid"
ProductType
required
string
Enum: "R001" "R002" "R003" "R004" "R005" "R006"
cardKey
string

Optional — card cardKey to narrow the fee lookup.

clientId
string

Optional — cardholder clientCode to narrow the fee lookup.

iban
string

Optional — account IBAN to narrow the fee lookup.

Responses

Response Schema: application/json
_id
string

Fee record _id.

deletedAt
string or null <date-time>

Soft-delete timestamp, null for active fee records.

GLAccountName
string

GL account name in the accounting system (e.g. Card Issuing Fees).

feeCode
string

Fee code (e.g. ISS1, DLV1).

operationType
string

Operation type this fee applies to (e.g. Card Issuing Fee, Card Delivery Fee).

customerType
string

Customer type this fee applies to (e.g. Consumer Debit).

productType
string

Product type this fee applies to (e.g. R001).

trigger
string

What triggers the fee (e.g. API Call).

loopOnCard
boolean

Whether the fee applies once per card or per transaction.

displayDescriptor
string

Human-readable descriptor shown in statements and admin UIs.

type
string

Fee class (e.g. Non Transactional).

currency
string

ISO 4217 currency code (e.g. EUR).

fixedFee
number <double>

Flat fee amount in currency.

percentageFee
number <double>

Percentage-based fee component, when applicable.

fxFixedFee
number <double>

Flat fee applied to FX transactions.

fxPercentageFee
number <double>

Percentage-based fee applied to FX transactions.

object (FeeSpecialCondition)

Special-condition block present on delivery-fee responses (and some issuing-fee responses). All keys are optional and reflect provider-specific overrides.

createdAt
string <date-time>
updatedAt
string <date-time>
__v
integer

Internal document version key.

property name*
additional property
any

Request samples

Content type
application/json
{
  • "CustomerType": "Consumer Debit",
  • "ProductType": "R001"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "deletedAt": "2019-08-24T14:15:22Z",
  • "GLAccountName": "string",
  • "feeCode": "string",
  • "operationType": "string",
  • "customerType": "string",
  • "productType": "string",
  • "trigger": "string",
  • "loopOnCard": true,
  • "displayDescriptor": "string",
  • "type": "string",
  • "currency": "string",
  • "fixedFee": 0.1,
  • "percentageFee": 0.1,
  • "fxFixedFee": 0.1,
  • "fxPercentageFee": 0.1,
  • "specialCondition": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "__v": 0
}

Webhooks

Everything a partner needs to receive and verify our outbound webhooks.

A partner-facing webhook is a POST we make to the url the partner configured, when a business process reaches its final outcome — an administrator approving or rejecting a B2B account, an individual, or a cardholder, or an IBAN settings / IBAN link change being applied. The partner configures a single endpoint and a signing secret; every event type goes to that one url, and what happened travels in the body's type.

The endpoints under this tag are the partner-facing management surface:

Endpoint What it does
GET /api/partner/webhooks/public-key Fetch the public key partners verify signatures with.
PUT /api/partner/webhooks/secret Set or rotate the partner's own signing secret.
GET /api/partner/webhooks/events List every supported event and whether it is on.
PATCH /api/partner/webhooks/events Switch one or more events on or off.
GET /api/partner/logs/webhooks Read the partner's own delivery history, one row per attempt.

Every endpoint is scoped to the partner id taken from the verified JWT — a partner physically cannot see another partner's deliveries, and there is no query parameter that widens the scope.

The delivery guarantee. One final business outcome produces one webhook. The platform recognises a repeated outcome and updates the delivery record it already holds instead of creating a second one, so a retried approval or a replayed job never announces the same outcome twice. A delivery that did not reach you is retried, reusing the same webhookId — see PartnerWebhookDeliveryBody for what you receive.

See the Webhooks guide in the documentation for the signature scheme, the full event catalogue, and the retry policy.

List the partner's outbound webhook delivery history

Every webhook the platform sends to this partner leaves a delivery log row. This endpoint returns those rows, so the partner can see what was sent, to which url, and whether it arrived.

Scoped to the calling partner. The rows are selected by the partner id taken from the verified JWT — never from the request body or a query parameter. A partner therefore sees only its own deliveries: another partner's webhooks and the platform's internal webhooks are never included, and there is no query parameter that can widen that scope.

The partner id is the stable identity of the recipient, so the history survives a configuration change: webhooks delivered to an earlier url stay in the list after the url is changed.

Read-only. There is no action here to resend or modify a delivery.

A row's responseStatus is the HTTP status the partner's endpoint answered with (200 on success, the failing status otherwise, null if the request never got a response).

The business outcome is in payloadSent.status (success / failed) — e.g. a cardholder that was declined is a delivery success with a payloadSent.status of failed.

The signing secret is never returned.

This is the read side of the partner webhooks. For how the webhooks themselves are delivered — the signature scheme, the event catalogue, and the retry policy — see the Webhooks guide in the documentation.

Authorizations:
JWTBearerAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number for pagination. Starts at 1. Default values depend on the endpoint: transactions default to 1, and audit/status-history endpoints default to 1.

limit
integer >= 1
Default: 50
Example: limit=50

Number of audit-log or card-status-history records to return per page. Defaults to 50. There is currently no enforced maximum limit value in the Partner API implementation. Pass a larger value directly, for example ?page=1&limit=3000.

Responses

Response Schema: application/json
success
boolean
count
integer
Array of objects (PartnerWebhookLogEntry)
object (Pagination)

Response samples

Content type
application/json
{
  • "success": true,
  • "count": 0,
  • "data": [
    ],
  • "pagination": {
    }
}

List the webhook events and whether each is switched on

Returns every event type the platform can send you, with its current on/off state.

An event you have never touched is on. Events are only delivered while the master switch (webhooks.isActive, set by your Paynovus administrator) is also on.

Scoped to the calling partner via the verified JWT.

Authorizations:
JWTBearerAuth

Responses

Response Schema: application/json
success
required
boolean
count
required
integer

The number of supported event types.

required
Array of objects (PartnerWebhookEvent)

Response samples

Content type
application/json
{
  • "success": true,
  • "count": 8,
  • "data": [
    ]
}

Switch one or more webhook events on or off

Sets the state of one or several events at once. Events you do not mention keep their current state. Repeating the same request is harmless. Returns the full event list after the change.

Switching an event off stops deliveries of that event only; the master switch and your url are unchanged.

Validation — events is required and must contain at least one entry. Each entry needs a known event type and a real boolean isActive; a string like "false" is rejected rather than coerced. Unknown fields are rejected, so a misspelled property is never silently ignored.

Authorizations:
JWTBearerAuth
Request Body schema: application/json
required
required
Array of objects (PartnerWebhookEvent) non-empty

The events to change. Events you do not mention keep their current state.

Array (non-empty)
event
required
string
Enum: "individual_onboarding_applicant_created" "individual_onboarding_applicant_declined" "b2b_account_created" "b2b_account_declined" "b2b_cardholder_approved" "b2b_cardholder_declined" "b2b_iban_settings_updated" "b2b_iban_linked"

The event type. One of the values the platform can send.

isActive
required
boolean

Whether this event is delivered to you. Defaults to true when omitted from the stored list.

Responses

Response Schema: application/json
success
required
boolean
count
required
integer

The number of supported event types.

required
Array of objects (PartnerWebhookEvent)

Request samples

Content type
application/json
{
  • "events": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "count": 8,
  • "data": [
    ]
}

Set or rotate the secret your webhooks are signed with

Sets the secret your webhooks are bound to. Our signature on every webhook covers a SHA-256 hash of this secret, so you can verify the webhook is ours and was made for your secret.

  • Send { "secretKey": "..." } (8-200 characters) to use your own value.
  • Send no secretKey and we generate a strong random secret and return it once in this response.
  • secretKey is the only accepted request property; unknown fields are rejected so a misspelled secret cannot be mistaken for success.

A validation failure returns 400 with the offending field and the reason in details.

The secret is stored encrypted and is write-only: no endpoint ever returns it again, so store it when you set it. Rotation takes effect immediately for webhooks sent after this call; there is no grace period for the old secret.

Authorizations:
JWTBearerAuth
Request Body schema: application/json
optional
secretKey
string [ 8 .. 200 ] characters

The secret your webhooks are signed with. Trimmed before it is stored.

Responses

Response Schema: application/json
success
required
boolean
hasSecret
required
boolean

Always true when the call succeeds — a secret is stored either way.

secretKeyGenerated
required
boolean

Whether the platform generated the secret instead of using a supplied secretKey. When false, the secret you sent is now in force.

secretKey
string

Only present when secretKeyGenerated is true, and only this once.

Request samples

Content type
application/json
{
  • "secretKey": "my-own-long-random-secret"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "hasSecret": true,
  • "secretKeyGenerated": false
}

Get the public key that verifies our webhook signatures

Every webhook carries an X-Payload-Signature header: an Ed25519 signature (base64) made with a private key only the platform holds. The signed message is sha256hex(yourSecret) + "." + rawBody, so verifying it with the key returned here proves the webhook came from us, is unaltered, and was made for your secret. The secret itself is never sent. X-Payload-Key-Id tells you which key signed it, so you can pick the right one after a rotation.

Returns 503 if signing is not configured on this environment (webhooks are not sent there either).

Authorizations:
JWTBearerAuth

Responses

Response Schema: application/json
success
required
boolean
keyId
required
string

The id of the signing key, matching the X-Payload-Key-Id header.

algorithm
required
string
Value: "ed25519"
publicKey
required
string

The public key in SPKI PEM format.

Response samples

Content type
application/json
{
  • "success": true,
  • "keyId": "9f86d081884c7d65",
  • "algorithm": "ed25519",
  • "publicKey": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n"
}