Skip to main content

Payment Instruments

Introduction​

The Payment Instruments module exposes features for managing payment instruments such as bank accounts.

Payment Instrument Service​

The PaymentInstrumentService can be used for managing payment instrument related operations.

Get Payment Instruments​

Use getAll function to retrieve a list of payment instruments.PaymentInstrumentsParameters is used to filter the response by instrument type using instrumentType and by payment option using paymentOption. undefined can be passed instead of PaymentInstrumentsParameters if there are no filters applied.

import { Wallet } from '@paysafe/paysafe-wallet-saas-web/wallet';
import { PaymentInstrumentsParameters } from '@paysafe/paysafe-wallet-saas-web/payment-instruments';
import { InstrumentType, PaymentOptionType } from '@paysafe/paysafe-wallet-saas-web/common';

/**
 * You can choose to provide none, one or both parameters.
 */
const paymentInstrumentsParameters: PaymentInstrumentsParameters = {
    instrumentType: InstrumentType.US_BANK_ACCOUNT,
    paymentOption: PaymentOptionType.BANK_TRANSFER
};

Wallet.getInstance().getPaymentInstrumentService().getAll(paymentInstrumentsParameters)
  .then(response => console.log('Payment instruments', response))
  .catch(error => console.error('Error fetching payment instruments', error));

Get Payment Instrument​

Use get function to retrieve a single instrument with specific type and identifier. PaymentInstrumentParameters are used to filter the response.

import { Wallet } from '@paysafe/paysafe-wallet-saas-web/wallet';
import { PaymentInstrumentParameters } from '@paysafe/paysafe-wallet-saas-web/payment-instruments';
import { InstrumentType } from '@paysafe/paysafe-wallet-saas-web/common';


const paymentInstrumentParameters: PaymentInstrumentParameters = {
    instrumentId: '6598347939',
    instrumentType: InstrumentType.US_BANK_ACCOUNT
};

Wallet.getInstance().getPaymentInstrumentService().get(paymentInstrumentParameters)
  .then(response => console.log('Payment instrument', response))
  .catch(error => console.error('Error fetching payment instrument', error));

Delete Single Payment Instrument​

Use delete function to remove specific payment instrument filtered by PaymentInstrumentParameters.

import { Wallet } from '@paysafe/paysafe-wallet-saas-web/wallet';
import { PaymentInstrumentParameters } from '@paysafe/paysafe-wallet-saas-web/payment-instruments';
import { InstrumentType } from '@paysafe/paysafe-wallet-saas-web/common';

const paymentInstrumentParameters: PaymentInstrumentParameters = {
    instrumentId: '6598347939',
    instrumentType: InstrumentType.US_BANK_ACCOUNT
};
Wallet.getInstance().getPaymentInstrumentService().delete(paymentInstrumentParameters)
    .then(response => console.log('Payment instrument', response))
    .catch(error => console.error('Error fetching payment instruments', error));

Start Instrument Verification​

Use startVerification function to create new instrument verification session. You should call this function first when you want to add a new payment instrument. It returns an InstrumentVerification object that represents the session for instrument verification.

import { Wallet } from '@paysafe/paysafe-wallet-saas-web/wallet';
import { InstrumentVerificationRequest } from '@paysafe/paysafe-wallet-saas-web/payment-instruments';
import { InstrumentType } from '@paysafe/paysafe-wallet-saas-web/common';


const requestBody: InstrumentVerificationRequest = {
    instrumentType: InstrumentType.US_BANK_ACCOUNT,
    returnUrl: '<valid url>'
};

Wallet.getInstance().getPaymentInstrumentService().startVerification(requestBody)
  .then(response => console.log('Created instrument verification', response))
  .catch(error => console.error('Error creating instrument verification', error));

Get Single Instrument Verification Session​

Use getVerification function to verify the status and retrieve an instrument verification session.

import { Wallet } from '@paysafe/paysafe-wallet-saas-web/wallet';

const sessionId = '1234567890';

Wallet.getInstance().getPaymentInstrumentService().getVerification(sessionId)
  .then(response => console.log('Instrument verification', response))
  .catch(error => console.error('Error fetching instrument verification', error));

Get Instrument Verification Sessions​

Use getAllVerifications function to retrieve a list of instrument verification sessions. undefined can be passed instead of InstrumentVerificationParameters.

import { Wallet } from '@paysafe/paysafe-wallet-saas-web/wallet';
import {
    InstrumentVerificationParameters,
    InstrumentVerificationStatus
} from '@paysafe/paysafe-wallet-saas-web/payment-instruments';

const verificationQueryParameters: InstrumentVerificationParameters = {
    limit: 10,
    offset: 0,
    sessionStatus: InstrumentVerificationStatus.ACTIVE
};

Wallet.getInstance().getPaymentInstrumentService().getAllVerifications(queryParameters)
  .then(response => console.log('Active instrument verifications list', response))
  .catch(error => console.error('Error fetching instrument verifications list', error));

Pagination​

tip

You can achieve pagination by combining the limit and offset filters. For instance, implementing pagination with a page size of 10 results per page would involve configuring:

  • Page 1: limit=10, offset=0 
    const verificationQueryParameters: InstrumentVerificationParameters = {
      limit: 10,
      offset: 0,
      sessionStatus: InstrumentVerificationStatus.ACTIVE
    };
  • Page 2: limit=10, offset=10
  • Page 3: limit=10, offset=20

Verifying an Instrument​

Cards​

Throughout the use of a card instrument, at certain points you will be required to verify it. The most common cases are when:

  • Nearing the card's deposit limit.
  • Reaching the card's deposit limit.

The way to detect that a card instrument requires verification is when the PaymentInstrument has a status of VERIFICATION_REQUIRED and we provide the following ways to verify it.

note

For a card verification to take place at least one successful deposit must be made and the VERIFICATION_REQUIRED status must be present on the card instrument.

Verifying a Card Instrument

The PaymentInstrumentService provides a verifyCard method for card instrument verification which expects a CardVerificationRequest object.

warning

If a deposit above the limit threshold is made, an error indicating that the limit is exceeded will be returned. In that case you have to make at least one succesful deposit below the limit threshold.

import { Wallet } from '@paysafe/paysafe-wallet-saas-web/wallet';
import { CardVerificationRequest, CardVerificationType } from '@paysafe/paysafe-wallet-saas-web/payment-instruments';

const verifyCardRequest : CardVerificationRequest = {
    verificationCode: '1234',
    instrumentId: '123456',
    verificationType: CardVerificationType.VERIFICATION_CODE
};

Wallet.getInstance().getPaymentInstrumentService().verifyCard(verifyCardRequest)
    .then(response => console.log('Verify card', response))
    .catch(error => console.error('Error verifying card instrument', error));
Helper methods

The PaymentInstrumentService also provides a handful of methods to either inspect a card instrument's verification information or query the verification attempts made on the instrument.

  • To inspect a card instrument's verification information you have to call the getCardVerificationInformation method on the PaymentInstrumentService by passing the id of the card instrument.
import { Wallet } from '@paysafe/paysafe-wallet-saas-web/wallet';

const instrumentId: string= '1001';

Wallet.getInstance().getPaymentInstrumentService().getCardVerificationInformation(instrumentId)
    .then(response => console.log('Verification information', response));
  • To get all the verification attempts on a card instrument, you have to call the getCardVerifications on the PaymentInstrumentService passing an optional CardVerificationsParameters object.
import { Wallet } from '@paysafe/paysafe-wallet-saas-web/wallet';
import { CardVerificationsParameters } from '@paysafe/paysafe-wallet-saas-web/payment-instruments';

const cardVerificationsParameters: CardVerificationsParameters = {
    limit: 10,
    offset: 10,
    status: "COMPLETED",
    instrumentId: "123456"
};

Wallet.getInstance().getPaymentInstrumentService().getCardVerifications(cardVerificationsParameters)
    .then(response => console.log('Card verification attempts', response))
    .catch(error => console.error('Error fetching card verification attempts', error));
  • You could also get a single verification attempt on a card instrument by calling the getSingleCardVerification method on the PaymentInstrumentService and passing a verificationID string parameter.
import { Wallet } from '@paysafe/paysafe-wallet-saas-web/wallet';

const verificationId: string = '2cb56b2749af52d6b257054ef3de0';

Wallet.getInstance().getPaymentInstrumentService().getSingleCardVerification(verificationId)
    .then(response => console.log('Card verification attempt', response))
    .catch(error => console.error('Error fetching card verification attempt', error));