Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Cards

Create Card

Use this endpoint to create a user and issue a card without the Card Onboarding flow. It can only be used with card programs that have KYC/IDV bypass enabled (see Bypass KYC/IDV). It supports Prepaid Card and Secured Credit Card programs; the card type is determined by the CardProgramId.

Method: POST

Endpoint: {{env}}/api/card/create

{
  "CardProgramId": "string",
  "UserId": "00000000-0000-0000-0000-000000000000",
  "FirstName": "string",
  "LastName": "string",
  "Email": "string",
  "PhoneNumber": "string",
  "DateOfBirth": "string",
  "ClientUserId": "string",
  "Language": "En",
  "AddressLine1": "string",
  "AddressLine2": "string",
  "AddressCity": "string",
  "AddressState": "string",
  "AddressPostalCode": "string",
  "AddressCountry": "string"
}
{
    "statusCode": 200,
    "message": "POST Request successful.",
    "isError": false,
    "result": {
        "FirstName": "string",
        "LastName": "string",
        "Email": "string",
        "PhoneNumber": "string",
        "DateOfBirth": "string",
        "CustomerId": "00000000-0000-0000-0000-000000000000",
        "OnboardId": "00000000-0000-0000-0000-000000000000",
        "OnboardStatus": "string",
        "SessionId": "string",
        "UserId": "00000000-0000-0000-0000-000000000000",
        "ClientUserId": "string",
        "UserCardId": "00000000-0000-0000-0000-000000000000",
        "CardType": "string",
        "AddressLine1": "string",
        "AddressLine2": "string",
        "AddressCity": "string",
        "AddressState": "string",
        "AddressPostalCode": "string",
        "AddressCountry": "string"
    }
}

Input Parameters

Parameter
Type
Mandatory
Description

CardProgramId

String

Yes

Card Program ID to issue the card under

UserId

Guid

No

Existing user to issue the card to. When provided, profile fields are not required

FirstName

String

Yes, if UserId is not provided

First name

LastName

String

Yes, if UserId is not provided

Last name

Email

String

Yes, if UserId is not provided

Email address

PhoneNumber

String

Yes, if UserId is not provided

Mobile phone number

DateOfBirth

String

Yes, if UserId is not provided

Date of birth, MM/dd/yyyy

Language

String

No

Cardholder language

ClientUserId

String

No

Your own identifier for the user

AddressLine1

String

Yes¹

Address line 1

AddressLine2

String

No

Address line 2

AddressCity

String

Yes¹

City

AddressState

String

Yes¹

Province code

AddressPostalCode

String

Yes¹

Postal code

AddressCountry

String

Yes¹

Country

CreditLimitRequested

Decimal

Yes, for Secured Credit Card

Requested credit limit. Must be within the program's minimum and maximum

¹ Required for Secured Credit Card programs. For Prepaid Card programs, required unless your program is configured to not require an address.

Response

Field
Type
Description

FirstName

string

The legal first name of the profile holder.

LastName

string

The legal last name of the profile holder.

Email

string

The registered email address for the user profile.

PhoneNumber

string

The verified phone number for the profile.

DateOfBirth

string

The user's date of birth as recorded in the system.

CustomerId

Guid

The unique identifier for the customer record.

OnboardId

Guid

The unique identifier for the specific onboarding session.

OnboardStatus

string

The current state of the onboarding process.

SessionId

string

The identifier for the active verification or onboarding session.

UserId

Guid

The unique identifier for the user in the BaaS platform.

ClientUserId

string

The external identifier provided by the client for the user.

UserCardId

Guid

The unique identifier for the card associated with this user.

CardType

string

The category of the issued card (e.g., Prepaid, Secured).

CardHolderPortalUrl

string

The URL where the cardholder can access their management portal.

AddressLine1

string

The primary line of the user's registered address.

AddressLine2

string

The secondary line of the user's address.

AddressCity

string

The city of the user's address.

AddressState

string

The state or province of the user's address.

AddressPostalCode

string

The postal or zip code of the user's address.

AddressCountry

string

The country code of the user's address.

Errors

Errors are returned with HTTP 400. Multiple missing fields are returned together, e.g. "FirstName is required; Email is required".

Message
Reason

Card program does not support bypass KYC onboarding.

KYC/IDV bypass is not enabled on the card program

Credit limit requested is required for secured card applications

CreditLimitRequested missing for a Secured Credit Card

Credit limit requested must be at least {min} / must not exceed {max}

CreditLimitRequested outside the program's range

Error - Card Program Id {CardProgramId} does not exist for customer {CustomerId}.

Card program not found on your account

User not found.

UserId does not exist

User already has a {card type} that is not closed (status: {status}). Close the existing card before creating a new one.

User already holds a non-closed card of this card type

Invalid province selected for the card program.

AddressState is not enabled for the card program

Activate Card

Use this endpoint to set the users current prepaid card status to Activated.

Method: POST

Endpoint: {{env}}/api/card/activate-card

For physical cards, set the cardholder's PIN with Set PIN. Cardholders activating from the Cardholder Portal are asked to confirm the last 4 digits and expiry date of their physical card and to set a PIN.

Input Parameters

Parameter
Type
Mandatory
Description

UserId

Guid

Yes

User Id

UserCardID

Guid

Yes

Id of the specific card type issued (e.g. Prepaid Card User Id)

Response

Parameter
Type
Description

ResponseDesc

String

Description of the response

Update Card Program

Use this endpoint to update the card program of the current card attached to the user.

Method: POST

Endpoint: {{env}}/api/card/update-card-program

Input Parameters

Parameter
Type
Mandatory
Description

UserId

Guid

Yes

User Id

UserCardId

Guid

Yes

Id of the specific card type issued (e.g. Prepaid Card User Id)

NewProgramId

String

Yes

New Card Program Id (Case Sensitive)

Response

Parameter
Type
Description

CardReferenceId

String

Card Reference Id

NewProgramId

String

New Card Program Id

ResponseDesc

String

Response description

Get Cards

Use this endpoint to gather all the cards attached to the user.

Method: GET

Endpoint: {{env}}/api/card/get-cards/{{userId}}

Input Parameters

Parameter
Type
Mandatory
Description

UserId

Guid

Yes

User Id

Response

Id
Guid
The unique identifier for the User Card

CardBrand

string

The brand of the card (e.g., Visa, Mastercard).

CardType

string

The functional type of the card (Prepaid or Secured).

CardApplicationStatus

string

The current status of the card application.

OnboardStatus

string

The status of the user onboarding process for this card.

CardNumber

string

The masked or truncated card number.

ExpireMonth

string

The two-digit expiration month of the card.

ExpireYear

string

The expiration year of the card.

CardStatus

string

The operational status of the card (e.g., Active, Blocked, Closed).

CardOnboardingStatus

string

Specific onboarding step reached for the card.

CardReferenceId

string

The external reference identifier from the card processor.

CardRegistrationStatus

string

Indicates if the card has been registered by the user.

CardholderUserId

string

The identifier of the user who holds the card.

CardProgramId

string

The identifier of the card program this card belongs to.

CardholderId

string

The processor-specific cardholder identifier.

AvailableBalance

decimal

The amount of funds currently available for spending.

LedgerBalance

decimal

The total balance including pending transactions.

CustomerId

string

The unique identifier for the customer (tenant).

OnboardId

string

The identifier for the specific onboarding session.

CreatedAt

DateTime

The timestamp when the card record was created.

CardActivatedAt

DateTime

The timestamp when the card was activated.

CardClosedAt

DateTime

The timestamp when the card was closed.

VirtualCard

string

Y if the card is a virtual card, otherwise N.

PhysicalCard

string

Y if the card is a physical card, otherwise N.

FulfillmentStatus

string

Physical card fulfillment status: Ordered, Shipped, Delivered. Null for virtual cards.

FulfillmentType

string

Physical card shipping type: Standard, Expedited. Null for virtual cards.

IDVVerification

string

How identity verification was completed: Bypassed, Not Bypassed, KYC Completed by Customer.

PendingAmount

decimal

The sum of all transactions currently in a pending state.

CreditLimitRequested

decimal

The credit limit amount requested by the applicant.

CreditLimit

decimal

The total approved credit limit for the card.

SecurityDepositAmount

decimal

The amount held as a security deposit for secured cards.

SecurityDepositCardNumber

string

The card number associated with the security deposit.

SecurityDepositCardReferenceId

string

The reference ID for the security deposit card.

LastPaymentDate

string

The date of the last payment made on the account.

LastPaymentAmount

decimal

The amount of the most recent payment.

MinimumPaymentAmount

decimal

The minimum amount required for the next payment.

MinimumPaymentDueDate

string

The deadline for making the minimum payment.

StatementDate

string

The date when the most recent statement was generated.

StatementAmount

decimal

The total balance due on the last statement.

IsPrimaryCard

Boolean

Whether the card is the Primary card for the card type.

SharedBalanceGroupId

Guid

Identifier shared by all cards that share the same balance or credit line.

SiblingCards

Array

Other cards in the same shared-balance group, excluding the current card. See below.

WalletProvisionings

Array

Digital wallets the card has been added to. See below.

SiblingCards

Parameter
Type
Description

Id

Guid

The unique identifier for the sibling User Card

CardReferenceId

String

The external reference identifier from the card processor

IsPrimaryCard

Boolean

Whether the sibling card is the Primary card of the group

CardStatus

String

The operational status of the sibling card

PhysicalCard

Boolean

Whether the sibling card is a physical card

Last4Digits

String

Last 4 digits of the sibling card number

WalletProvisionings

Parameter
Type
Description

Id

Guid

The unique identifier for the wallet provisioning

DeviceName

String

Name of the device the card was added to

WalletType

String

ApplePay, GooglePay, SamsungPay, Unknown

Status

String

Added, Suspended, Resumed, PendingStepUp, Unknown. Removed and declined wallet tokens are not listed.

TokenRequesterId

String

Identifier of the wallet provider

EventDate

DateTime

Date and time of the latest wallet event

Update Card Status

Use this endpoint to set the card status of the user’s current card.

Method: POST

Endpoint: {{env}}/api/card/update-card-status

Request Parameters

Parameter
Type
Mandatory
Description

UserId

Guid

Yes

User Id

UserCardId

Guid

Yes

Id of the specific card type issued (e.g. Prepaid Card User Id)

CardStatus

String

Yes

New Card Status. Allowed values: Activated, Inactive, FraudBlock, Closed

Response

Parameter
Type
Description

CardStatus

String

Card Status

ResponseDesc

String

Response description

Card Status

These are the available card status updates.

Card Status
Description

Issued&inactive

Card is issued and not activated yet (default card status on new and reissued card)

Activated

Card is active and ready for use.

Closed

Card account is closed.

Inactive

Card is temporarily inactive.

FraudBlock

Card is blocked due to suspected fraud.

Secured Credit Card: when a card with a remaining Security Deposit is closed, the full Security Deposit is automatically unloaded to your Zūm Wallet before the card is closed. A card with an outstanding balance cannot be closed.

Sandbox: set SimulationEvent to UnloadFailing to simulate a failed Security Deposit unload.

These are the available card statuses that can be returned.

Card Status
Description

PendingCardIssuance

Card is not issued yet

Issued&inactive

Card is issued and not activated yet

Activated

Card is active and ready for use.

Closed

Card account is closed.

Inactive

Card is temporarily inactive.

FraudBlock

Card is blocked due to suspected fraud.

These are the available card application statuses when the User is in the process of applying for the card and the card is not yet issued.

Card Status
Description

PendingApproval

Card application has passed KYC/IDV and not yet approved for card issuance

UnderReview

Card application is under review

Rejected

Card application is declined

Approved

Card application is approved for card issuance

InProgress

Card application KYC/IDV verification is submitted and process is in progress

Incomplete

Card application has completed the card profile setup and KYC/IDV step has not been completed

Errors

Message

Card cannot be closed when there is an outstanding balance.

Unload failed while attempting to close card, view transaction details for more info.

Reissue Card

Use this endpoint to reissue an existing non-closed card and close the existing card attached to the user. The reissued card will have a new card number, new expire date, and new CVC.

Method: POST

Endpoint: {{env}}/api/card/reissue-card

Reissue Card does not convert a virtual card to a physical card. Use Order Physical Card.

Request Parameters

Parameter
Type
Required
Description

UserId

guid

yes

User Id

UserCardId

guid

yes

Id of the specific card type issued (e.g. Prepaid Card User Id)

IsLostOrStolen

Boolean

No

Set to true when the card is being replaced because it was lost or stolen

CardShipmentType

String

No

Physical cards only. Standard or Expedited

ShippingAddress

Object

No

Physical cards only. Updates the shipping address for the replacement card

Response

Parameter
Field
Description

NewCardReferenceId

String

New Card Reference Id

ResponseDesc

String

Response description

UserId

Guid

User Id of the prepaid card user

Last4Digits

Number

Last 4 digits of the prepaid card number

ExpireMonth

String

Expiry month of the prepaid card number

ExpireYear

String

Expiry year of the prepaid card number

Available balance

Number

Available balance of the prepaid card number

Ledger Balance

Number

Ledger balance of the prepaid card number

FirstName

String

First name of the prepaid card user

LastName

String

Last name of the prepaid card user

CardStatus

String

Card status of the reissued card

CardProgramId

String

Card program the reissued card is assigned under

Email

String

Email address of the prepaid card user

Order Physical Card

Use this endpoint to order a physical card for a user's current virtual card. The card is reissued onto the linked physical card program with a new card number.

Method: POST

Endpoint: {{env}}/api/card/order-physical-card

Input Parameters

Parameter
Type
Mandatory
Description

UserId

Guid

Yes

User Id

UserCardId

Guid

Yes

Id of the user's current card

CardShipmentType

String

No

Standard or Expedited. Must be enabled for the card program

ShippingAddress

Object

Yes

Shipping address (AddressLine1, AddressLine2, AddressCity, AddressState, AddressPostalCode, AddressCountry). PO Boxes are not accepted

Add Secondary Card

Use this endpoint to issue an additional card of the same card type to a user. The new card shares the balance (Prepaid Card) or credit line (Secured Credit Card) of the user's Primary card. Multiple card issuance must be enabled on your account.

Method: POST

Endpoint: {{env}}/api/card/add-secondary-card

Input Parameters

Parameter
Type
Mandatory
Description

UserId

Guid

Yes

User Id

UserCardId

Guid

Yes

Id of the user's Primary card

IsPhysical

Boolean

Yes

true to issue a physical card, false for virtual

CardShipmentType

String

Yes, physical only

Standard or Expedited

ShippingAddress

Object

No

Physical cards only. Shipping address (AddressLine1, AddressLine2, AddressCity, AddressState, AddressPostalCode, AddressCountry)

Nickname

String

No

Nickname for the new card

Requires permission to update user card details.

Response

Returns the new card in the same format as a card in Get Cards, including SiblingCards.

Errors

All errors return HTTP 400.

Message
Cause

UserId and UserCardId are required.

UserId or UserCardId is missing

Card with id {id} not found.

The card was not found

Card with id {id} is not a primary card. A secondary card can only be linked against the primary of a shared-balance group.

UserCardId is not the Primary card

Card with id {id} is closed or has never been activated. A secondary card cannot be linked.

The Primary card is closed or was never activated

BaasUser {id} has not passed KYC/IDV verification and is not eligible to hold multiple cards.

The user is not KYC/IDV verified (including users created with Bypass KYC/IDV)

Customer {id} does not have multi-card issuance enabled for {CardType}.

Multiple card issuance is not enabled for the card type

Shipment type is required to issue a physical secondary card.

CardShipmentType is missing for a physical card

You've reached the maximum number of physical cards for your account.

Physical card limit reached

You've reached the maximum number of virtual cards for your account.

Virtual card limit reached

To remove a secondary card, set its status to Closed with Update Card Status. Closing the Primary card closes all cards in the group.

Get Card Transactions

Use this endpoint for transaction history from a users prepaid card.

Method: POST

Endpoint: {{env}}/api/user/get-card-transactions

Request Parameters

UserId
Guid
Yes
User Id

CardReferenceId

String

Yes

Card reference id

CardTransactionType

String

No

Card issuer transaction type

CardTransactionStatuses

String

No

Card transaction statuses

TransactionZumRailsType

String

No

Transaction zum rails type

CardTransactionId

String

No

Card issuer transaction id

GenericSearch

String

No

Filter the search with this text

AmountLowerLimit

Number

No

Lower limit transaction amount

AmountUpperLimit

Number

No

Upper limit transaction amount

CreatedAtOperator

String

No

Date filter type for query

CreatedAtFrom

Datetime

No

Start date for query

CreatedAtTo

Datetime

No

End date for query

CreatedAt

Datetime

No

Base date for query

Timezone

Windows or IANA

No

Timezone identifier

Pagination

-

Yes

PageNumber

Number

Yes

The respective page, starting at 1

ItemsPerPage

Number

Yes

The amount of items per page between 0 and 100

Response

Parameter
Type
Description

CurrentPage

Number

Current page of transaction list

PageSize

Number

Number of items in page requested

TotalCount

Number

Number of total items queryable

Items

Id

Guid

Zum Rails Transaction Id

CreatedAt

Datetime

Created at date and time

SettlementDate

Date

Date funds settled

TransactionId

String

Card issuer transaction id

Description

String

Description of transaction

Status

String

Status of transaction

Debit

Decimal

Amount Debited

Credit

Decimal

Amount Credited

MerchantNameAndLocation

String

Merchant name and location

CreatedAtOperator:

Type
Description

IsInTheLast

Between user creation date and now

ExactlyMatches

Exactly matches CreatedAt

IsBetween

Is between CreatedAtFrom and CreatedAtTo

IsAfter

Is after CreatedAt

IsOnOrAfter

Is on or after CreatedAt

IsBefore

Is before CreatedAt

IsBeforeOrOn

Is before or on CreatedAt

CardTransactionStatuses:

Type
Description

Posted

Posted transactions

Pending

Pre Auth Transactions

Declined

Declined Transcations

CardTransactionType:

Type
Description

POS

POS Purchase

ATM

Cash Withdrawal

Debit

Debit Transactions

Credit

Credit Transactions

Cancel Transactions

Use this endpoint for reversing pre-auth POS transactions and fee transactions.

Method: DELETE

Endpoint: {{env}}/api/card-transaction/{transactionId}

Get Statement List

Use this endpoint to retrieve a paginated list of card statements for a User.

Method: POST

Endpoint: {{env}}/api/card/statements/filter

Request Parameters

Parameter
Type
Mandatory
Description

UserId

Guid

Yes

User Id

UserCardId

Guid

No

Id of the specific card type issued (e.g. Secured Credit Card User Id)

AddTransactionDetails

Bool

No

Whether to include transactions in each statement.

Set to true or false.

Default: false

DateFrom

Datetime

No

Start date for query

DateTo

Datetime

No

End date for query

Pagination

No

PageNumber

Number

No

The respective page, starting at 1

ItemsPerPage

Number

No

The amount of items per page between 0 and 100

Response

Parameter
Type
Description

CurrentPage

Number

Current page of results

PageSize

Number

Number of items in page requested

TotalCount

Number

Total number of items queryable

Items

Id

Guid

Statement Id

UserCardId

Guid

Id of the Secured Credit Card associated with the statement

PeriodStart

DateOnly

Start date of the statement period

PeriodEnd

DateOnly

End date of the statement period

StatementDate

DateOnly

Date the statement was generated

PaymentDueDate

Datetime

Payment due date

CreatedAt

Datetime

Record creation timestamp

Last4Digits

String

Last 4 digits of the card number

CardType

String

Card type (e.g. SecuredCredit)

PreviousBalance

Decimal

Balance carried over from prior statement

Payments

Decimal

Total payments received

OtherCredits

Decimal

Other credits applied

Purchases

Decimal

Total purchases made

CashAdvance

Decimal

Total cash advances

InterestCharged

Decimal

Interest charged this period

FeeCharged

Decimal

Fees charged this period

NewBalance

Decimal

Closing balance of the statement

MinimumPaymentDue

Decimal

Minimum payment required

CreditLimit

Decimal

Credit limit of the card

AvailableCredit

Decimal

Available credit remaining

DaysAccountPastDue

Int

Number of days the account is past due

StatementGenerated

Bool

Whether the statement has been generated

Transactions

List

Transactions included if AddTransactionDetails is true

Transactions

Id

Guid

Internal Id assigned to the transaction

StatementId

Guid

Corresponding StatementId of the transaction

Last4Digits

Number

Last 4 digits of the card

CardStatus

String

Status of the card at the time of the transaction

Type

String

Transaction type

Description

String

Description of the transaction

TransactionDate

Datetime

Date and time the transaction occured

TransactionPostedDate

Datetime

Date and time the transaction was posted

Amount

Decimal

Transaction amount. Negative amount is a debit.

CreatedAt

Datetime

Record creation timestamp

TransactionId

String

Trace audit number of the statement transaction, used to reconcile statement lines with your records

TransactionType

String

Card processor transaction type code (e.g. LF, FC, 40)

MessageType

String

ISO 8583 message type (e.g. 0200, 0720, 0722)

Get Statement Transactions

Use this endpoint to retrieve a paginated list of card statement transactions for a User.

Returns a 404 if a StatementId is provided but not found for the user.

Method: POST

Endpoint: {{env}}/api/card/statements-transactions/filter

Request Parameters

Parameter
Type
Mandatory
Description

UserId

Guid

Yes

User Id

UserCardId

Guid

Yes

Filter by specific card. Id of the specific card type issued

StatementId

Guid

No

Filter by specific statement. Returns 404 if not found for user

Date

DateTime

No

Base date for query (used with DateOperator)

DateOperator

DateOperator

No

Date filter type for query

DateFrom

DateTime

No

Start date for range query

DateTo

DateTime

No

End date for range query

Pagination

No

PageNumber

Number

No

The respective page, starting at 1

ItemsPerPage

Number

No

The amount of items per page between 0 and 100

Response

Parameter
Type
Description

CurrentPage

Number

Current page of results

PageSize

Number

Number of items in page requested

TotalCount

Number

Total number of items queryable

Items

Id

Guid

Transaction Id

Last4Digits

String

Last 4 digits of the card number

UserCardId

Guid

Id of the card associated with the transaction

CardStatus

String

Status of the card at time of transaction

Type

String

Transaction type

Description

String

Description of the transaction

TransactionDate

DateTime

Date and time the transaction occurred

TransactionPostedDate

DateTime

Date and time the transaction was posted

Amount

Decimal

Transaction amount (negative = debit)

CreatedAt

DateTime

Record creation timestamp

TransactionId

String

Trace audit number of the statement transaction, used to reconcile statement lines with your records

TransactionType

String

Card processor transaction type code (e.g. LF, FC, 40)

MessageType

String

ISO 8583 message type (e.g. 0200, 0720, 0722)

DateOperator:

Type
Description

IsInTheLast

Between user creation date and now

ExactlyMatches

Exactly matches CreatedAt

IsBetween

Is between CreatedAtFrom and CreatedAtTo

IsAfter

Is after CreatedAt

IsOnOrAfter

Is on or after CreatedAt

IsBefore

Is before CreatedAt

IsBeforeOrOn

Is before or on CreatedAt

PIN Management

Get PIN encryption public key

Returns the RSA public key used to encrypt PIN values. Your account must be configured with an encryption key by the Zūm Rails team. Contact support to securely share the key.

Method: GET

Endpoint: {{env}}/api/customer/kms-public-key

Set PIN

Use this endpoint to set the PIN on a card for the first time.

Method: POST

Endpoint: {{env}}/api/card/pin/set

Input Parameters

Parameter
Type
Mandatory
Description

UserId

Guid

Yes

User Id

UserCardId

Guid

Yes

Id of the card

EncryptedPin

String

Yes

4-digit PIN encrypted with the Zūm Rails public key

Change PIN

Use this endpoint to change the PIN on a card.

Method: POST

Endpoint: {{env}}/api/card/pin/change

Input Parameters

Parameter
Type
Mandatory
Description

UserId

Guid

Yes

User Id

UserCardId

Guid

Yes

Id of the card

EncryptedCurrentPin

String

Yes

Current PIN, encrypted

EncryptedNewPin

String

Yes

New PIN, encrypted

Send PIN OTP

Sends a one-time passcode to the cardholder's email. Required before Reset PIN or Unblock PIN.

Method: POST

Endpoint: {{env}}/api/card/pin/otp/send

Input Parameters

Parameter
Type
Mandatory
Description

UserId

Guid

Yes

User Id

UserCardId

Guid

Yes

Id of the card

Purpose

String

Yes

Set, Reset, or Unblock

Verify PIN OTP

Use this endpoint to verify the one-time passcode received by the cardholder.

Method: POST

Endpoint: {{env}}/api/card/pin/otp/verify

Input Parameters

Parameter
Type
Mandatory
Description

UserId

Guid

Yes

User Id

UserCardId

Guid

Yes

Id of the card

OtpCode

String

Yes

Code received by the cardholder

Purpose

String

Yes

Set, Reset, or Unblock

Reset PIN

Use this endpoint to reset the PIN on a card. Requires a verified Reset OTP (valid for 10 minutes).

Method: POST

Endpoint: {{env}}/api/card/pin/reset

Input Parameters

Parameter
Type
Mandatory
Description

UserId

Guid

Yes

User Id

UserCardId

Guid

Yes

Id of the card

EncryptedNewPin

String

Yes

New PIN, encrypted

Unblock PIN

Use this endpoint to unblock a card's PIN.

Method: POST

Endpoint: {{env}}/api/card/pin/unblock

Input Parameters

Parameter
Type
Mandatory
Description

UserId

Guid

Yes

User Id

UserCardId

Guid

Yes

Id of the card

BypassOtpCode

Boolean

No

Default false. When false, a verified Unblock OTP is required

PIN errors

Message

Invalid request: PIN must be encrypted using the public key provided by Zum Rails.

Invalid request: decrypted PIN must be exactly 4 digits.

PIN management is only available on physical card programs.

Card with id {id} has set pin before, please call change pin api.

Card with id {id} cannot change its PIN to the same value.

Card with id {id} PIN was changed less than 24 hours ago.

Card with id {id} has its PIN blocked and must be unblocked before its PIN can be set or changed.

Card with id {id} does not have pin blocked.

Card with id {id} has not completed OTP verification for a PIN {purpose}, or the verification has expired.

Invalid OTP Code.

Get Recipients

Use this endpoint to list the Interac e-Transfer recipients a Prepaid cardholder has saved in the Cardholder Portal.

Method: POST

Endpoint: {{env}}/api/card/recipients/filter

Input Parameters

Parameter
Type
Mandatory
Description

UserId

Guid

Yes

User Id

RecipientStatus

String

No

Deleted to return removed recipients; otherwise active recipients

Response

Parameter
Type
Description

Id

Guid

Recipient Id

FirstName

String

Recipient first name

LastName

String

Recipient last name

Email

String

Recipient email

Status

String

Active or Deleted

CreatedAt

DateTime

Date the recipient was added

UpdatedAt

DateTime

Date the recipient was updated

DeletedAt

DateTime

Date the recipient was removed

Last updated

Was this helpful?