Funds

Confirm if you have sufficient funds before proceeding with a transaction.

Verify the availability of funds for a specific transaction. By accessing this API, you can seamlessly confirm the funds needed for a payment or transfer, ensuring successful transactions and reducing the risk of insufficient funds issues.

The following diagram illustrates the process flow for confirming funds through our API, in compliance with PSD2. The flow involves several stages, including user authentication, consent creation, authorization and verification.

snappi

POST/v1/funds-confirmations

Check funds availability

Verify the availability of funds for a specified account or transaction.

Determine if there are sufficient funds to complete a transaction, helping to prevent potential payment failures or overdrafts.

Headers

  • Name
    consentId
    Type
    string(uuid)
    Description

    The unique identifier for the consent provided by the user.

  • Name
    x-Request-ID
    Type
    string(uuid)
    Description

    ID of the request sent to the server, unique to the call, as determined by the initiating part.

  • Name
    Certificate
    Type
    string
    Description

    The certificate used for signing the request, in base64 encoding. Must be contained if a signature is contained.

  • Name
    ClientId
    Type
    string
    Description

    The unique identifier for the client or customer initiating the funds confirmation.

  • Name
    Ocp-Apim-Subscription-Key
    Type
    string
    Description

    A unique identifier related to the registered merchant in the snappi API environment, available within the application's details.

Body parameters

  • Name
    cardNumber
    Type
    string
    Description

    The full card number associated with the transaction for funds confirmation.

  • Name
    account
    Type
    string
    Description

    The account details to be checked for funds availability, relevant to the transaction. It includes:

    • iban: The International Bank Account Number (IBAN) for the payee's bank account.
    • bban: The Basic Bank Account Number (BBAN) for the payee's bank account.
    • pan: The primary account number (PAN) for the payee's account.
    • maskedPan: The partially masked PAN for the payee's account.
    • msisdn: The mobile station international subscriber directory number (MSISDN) for the payee's account.
    • currency(required): The currency type for the funds confirmation request.
  • Name
    payee
    Type
    string
    Description

    The name of the payee for the funds confirmation.

  • Name
    instructedAmount
    Type
    object
    Description

    The amount specified for the transaction instruction. It includes:

    • currency: The currency type for the transaction.
    • Amount: The amount value provided for the transaction.

Response attributes

  • Name
    fundsAvailable
    Type
    boolean
    Description

    Indicates whether the funds are available for the requested transaction. Available options: true, false.

  • Name
    tppMessages
    Type
    array
    Description

    The messages related to third-party providers (TPPs) included in the response.It includes:

    • category: The category classification of the TPP message. Enum values: 0(ERROR), 1 (WARNING).
    • code: The specific error code returned in the response. Enum values: 0 - 12.
    • path: The path where the TPP message is located.
    • text: The text of the TPP message.
  • Name
    links
    Type
    object
    Description

    The hyperlinks or references included in the response data.

  • Name
    statusCode
    Type
    integer
    Description

    The status code indicating the result of the funds confirmation request.

Request

POST
/v1/funds-confirmations
curl -X POST /v1/funds-confirmations \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'consentId: string' \
-H 'X-Request-ID: string' \
-H 'Certificate: string' \
-H 'ClientId: string' \
-H 'Ocp-Apim-Subscription-Key: string' \
-d '{"cardNumber":"string","account":{"iban":"string","bban":"string","pan":"string","maskedPan":"string","msisdn":"string","currency":"string"},"payee":"string","instructedAmount":{"currency":"string","Amount":"string"}}'

Response examples

{
"fundsAvailable": true
}

Responses

StatusDescription
200OK
400Bad Request
401Unauthorized
403Forbidden
404Not Found
405Method Not Allowed
409Conflict
POST/v2/consents/confirmation-of-funds

Generate a consent that defines access rights to specific accounts for a given PSU-ID.

Control access to dedicated accounts and manage recurring access permissions effectively.

Headers

  • Name
    x-Request-ID
    Type
    string(uuid)
    Description

    The unique request identifier associated with the transaction.

  • Name
    Certificate
    Type
    string
    Description

    The certificate used for authentication in the transaction.

  • Name
    ClientId
    Type
    string
    Description

    The client identifier associated with the transaction.

  • Name
    PSU_ID
    Type
    string
    Description

    Personalized Security User Identification linked to the transaction. The PSU's ID, as determined by the PSU. This ID is the identification of the PSU within the ASPSP and should contain the web user's username that requests the consent or initiates the payment.

  • Name
    Ocp-Apim-Subscription-Key
    Type
    string
    Description

    A unique identifier related to the registered merchant in the snappi API environment, available within the application's details.

Body parameters

  • Name
    account
    Type
    object
    Description

    Information regarding the account involved in the transaction. It includes:

    • iban: The International Bank Account Number (IBAN) for the transaction.
    • bban: The Basic Bank Account Number (BBAN) for the transaction.
    • pan: The primary account number (PAN) for the transaction.
    • maskedPan: The partially masked PAN for the transaction.
    • msisdn: The mobile station international subscriber directory number (MSISDN) for the transaction.
    • currency: The currency in which the transaction is being processed.
  • Name
    cardNumber
    Type
    string
    Description

    The card number linked to the transaction.

  • Name
    cardExpiryDate
    Type
    string<date-time
    Description

    The expiration date of the card used in the transaction.

  • Name
    cardInformation
    Type
    string
    Description

    Information related to the card used in the transaction.

  • Name
    registrationInformation
    Type
    string
    Description

    Information regarding the registration process for the transaction.

Response attributes

  • Name
    consentStatus
    Type
    string
    Description

    Reflects the status of the consent, with 0 as received, 1 as rejected, 2 as valid, 3 as revokedByPsu, 4 as expired and 5 as terminatedByTpp.

  • Name
    consentID
    Type
    string
    Description

    The unique identifier for the consent associated with the transaction.

  • Name
    scaMethods
    Type
    string
    Description

    The list of available SCA methods:

    • authenticationType: The type of SCA method. Available enum values: 0 = SMSOTP, 1 = CHIPOTP, 2 = PHOTOOTP, 3 = PUSHOTP.
    • authenticationVersion: The version of authentication being used for the SCA method.
    • authenticationMethodId: The identification number of the SCA method.
    • name: The name of the SCA method.
    • explanation: The description of the SCA method.
  • Name
    chosenScaMethod
    Type
    string
    Description

    The Strong Customer Authentication (SCA) method chosen for the transaction.

    • authenticationType: The type of authentication method. Available enum values: 0 = SMSOTP, 1 = CHIPOTP, 2 = PHOTOOTP, 3 = PUSHOTP.
    • authenticationVersion: The version of the authentication method.
    • authenticationMethodId: The identification number of the authentication method used for the transaction.
    • name: The name associated with the transaction.
    • explanation: A detailed explanation or reason related to the transaction.
  • Name
    challengeData
    Type
    string
    Description

    Data related to any challenge presented during the transaction. It includes:

    • image: An image associated with the transaction.
    • data: General data associated with the transaction.
    • imageLink: The link to the image associated with the transaction.
    • otpMaxLength: The maximum length of the one-time password (OTP) for the transaction.
    • otpFormat: The format in which the one-time password (OTP) is presented. Available options: 0 = CHARACTERS, 1 = INTEGER.
    • additionalInformation: Any additional relevant information pertaining to the transaction.
  • Name
    links
    Type
    array
    Description

    The links to other resources related to the consent.

  • Name
    message
    Type
    string
    Description

    A human-readable message or information related to the consent request.

  • Name
    authenticationSchemes
    Type
    array
    Description

    The list of authentication schemes included in the response.

  • Name
    links
    Type
    object
    Description

    The links associated with the error.

  • Name
    properties
    Type
    object
    Description

    The list of properties included in the response.

  • Name
    statusCode
    Type
    integer
    Description

    Represents the status code associated with the response.

  • Name
    tppMessages
    Type
    array
    Description

    The messages from the third-party provider related to the consent.It includes:

    • category: The category classification of the TPP message. Available enum values: 0(ERROR), 1(WARNING).
    • code: Represents different enumerated codes: 0 for CONSENTUNKNOWNEnum, 1 for SERVICEBLOCKEDEnum, 2 for "RESOURCEUNKNOWNEnum" and 3 for RESOURCEEXPIREDEnum.
    • path: The path where the TPP message is located.
    • text: The text of the TPP message.

Request

POST
/v2/consents/confirmation-of-funds
curl -X POST /v2/consents/confirmation-of-funds \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'X-Request-ID: string' \
-H 'Certificate: string' \
-H 'ClientId: string' \
-H 'PSU_ID: string' \
-H 'Ocp-Apim-Subscription-Key: string' \  
-d '{"account":{"iban":"string","bban":"string","pan":"string","maskedPan":"string","msisdn":"string","currency":"string"},"cardNumber":"string","cardExpiryDate":"2024-05-04T09:42:00+00:00","cardInformation":"string","registrationInformation":"string"}'

Response examples

{
"consentStatus": 0,
"consentId": "",
"scaMethods": [
{
  "authenticationType": 0,
  "authenticationVersion": "",
  "authenticationMethodId": "",
  "name": "",
  "explanation": ""
}
],
"chosenScaMethod": {
"authenticationType": 0,
"authenticationVersion": "",
"authenticationMethodId": "",
"name": "",
"explanation": ""
},
"challengeData": {
"image": "",
"data": [
  ""
],
"imageLink": "",
"otpMaxLength": "",
"otpFormat": 0,
"additionalInformation": ""
},
"links": "",
"message": ""
}

Responses

StatusDescription
201Created
400Bad Request
401Unauthorized
403Forbidden
404Not Found
405Method Not Allowed
406Not Acceptable
409Conflict
429Too Many Requests
POST/v2/consents/confirmation-of-funds/{consentId}/authorisations

Initiate the authorisation process of confirming funds related to a specific consent.

Trigger the necessary steps to complete the authorization flow and obtain relevant challenge data and authentication methods.

Path parameters

  • Name
    consentId
    Type
    string
    Description

    Unique identifier for the consent being authorised.

Headers

  • Name
    x-Request-ID
    Type
    string(uuid)
    Description

    ID of the request, unique to the call, as determined by the initiating part.

  • Name
    Certificate
    Type
    string
    Description

    The certificate used for signing the request, in base64 encoding. Must be contained if a signature is contained.

  • Name
    ClientId
    Type
    string
    Description

    The client identifier issued to the TPP by the ASPSP.

  • Name
    PSU_ID
    Type
    string
    Description

    The PSU's ID, as determined by the PSU. This ID is the identification of the PSU within the ASPSP and should contain the web user's username that requests the consent or initiates the payment.

  • Name
    Ocp-Apim-Subscription-Key
    Type
    string
    Description

    A unique identifier related to the registered merchant in the snappi API environment, available within the application's details.

Response attributes

  • Name
    scaStatus
    Type
    string
    Description

    The status of the Strong Customer Authentication (SCA) process in the response. Min length= 1.

  • Name
    authorisationId
    Type
    string
    Description

    The unique ID of the authorisation.

  • Name
    scaMethods
    Type
    array
    Description

    The available Strong Customer Authentication (SCA) methods for the consent authorisation:

    • authenticationType: The type of authentication method to use with the SCA method. Enum values: 0 - 3.
    • authenticationVersion: The version of the authentication method to use with the SCA method.
    • authenticationMethodId: The ID of the authentication method to use with the SCA method.
    • name: The name of the SCA method.
    • explanation: The description of the SCA method.
  • Name
    chosenScaMethod
    Type
    array
    Description

    This parameter indicates the selected Strong Customer Authentication (SCA) method for the consent authorisation. It includes:

    • authenticationType: The type of authentication method to use with the SCA method. Enum values: 0 - 3.
    • authenticationVersion: The version of the authentication method to use with the SCA method.
    • authenticationMethodId: The ID of the authentication method to use with the SCA method.
    • name: The name of the SCA method.
    • explanation: The description of the SCA method.
  • Name
    challengeData
    Type
    string
    Description

    It contains the data related to the challenge presented during the authorisation process:

    • image: It refers to the image associated with the consent authorisation process.
    • data: The data parameter contains the information related to the consent authorisation process.
    • imageLink: The URL link to the image associated with the consent authorisation.
    • otpMaxLength: The maximum length allowed for the one-time password (OTP) during the authorisation process.
    • otpFormat: The format or structure of the One Time Password (OTP) required for authorisation, with values indicating character or integer format. Available options: 0, 1.
    • additionalInformation: Any additional information relevant to the consent authorisation process.
  • Name
    links
    Type
    object
    Description

    Links to additional resources or related information for the consent authorisation.

  • Name
    psuMessage
    Type
    string
    Description

    Message for the payment service user (PSU) during the authorisation.

  • Name
    authenticationSchemes
    Type
    array
    Description

    The list of authentication schemes for the consent authorisation.

  • Name
    links
    Type
    object
    Description

    The links parameter provides links to additional resources or related information.

  • Name
    statusCode
    Type
    integer
    Description

    The HTTP status code of the response.

  • Name
    properties
    Type
    object
    Description

    The properties parameter contains the list of properties related to the consent authorisation.

  • Name
    tppMessages
    Type
    array
    Description

    The list of messages related to the TPP (Third-Party Provider) for the consent authorisation process.It includes:

    • category: The category of the message.
    • code: Response parameter representing different error codes. Possible values: 0 for FORMATERROREnum, 1 for PARAMETERNOTCONSISTENTEnum, 2 for PARAMETERNOTSUPPORTEDEnum, 3 for SERVICEINVALIDEnum, 4 for RESOURCEUNKNOWNEnum, 5 for RESOURCEEXPIREDEnum, 6 for RESOURCEBLOCKEDEnum, 7 for TIMESTAMPINVALIDEnum, 8 for PERIODINVALIDEnum, 9 for SCAMETHODUNKNOWNEnum, 10 for CONSENTUNKNOWNEnum, 11 for SESSIONSNOTSUPPORTEDEnum and 12 for INVALIDTOTALAMOUNTEnum.
    • path: The path of the message.
    • text: The text of the message.

Request

POST
/v2/consents/confirmation-of-funds/{consentId}/authorisations
curl -X POST /v2/consents/confirmation-of-funds/{consentId}/authorisations \
-H 'Accept: application/json' \
-H 'X-Request-ID: string' \
-H 'Certificate: string' \
-H 'ClientId: string' \
-H 'PSU_ID: string' \
-H 'Ocp-Apim-Subscription-Key: string'

Response examples

{
"scaStatus": "",
"authorisationId": "",
"scaMethods": [
{
  "authenticationType": 0,
  "authenticationVersion": "",
  "authenticationMethodId": "",
  "name": "",
  "explanation": ""
}
],
"chosenScaMethod": {
"authenticationType": 0,
"authenticationVersion": "",
"authenticationMethodId": "",
"name": "",
"explanation": ""
},
"challengeData": {
"image": "",
"data": [
  ""
],
"imageLink": "",
"otpMaxLength": "",
"otpFormat": 0,
"additionalInformation": ""
},
"links": "",
"psuMessage": ""
}

Responses

StatusDescription
201Created
400Bad Request
401Unauthorized
403Forbidden
404Not Found
405Method Not Allowed
406Not Acceptable
409Conflict
429Too Many Requests
GET/v2/consents/confirmation-of-funds/{consentId}/status

Retrieve the status of a consent's Strong Customer Authentication (SCA) process.

Determine the current stage of the SCA workflow and monitor the progress of consent authorization.

Path parameters

  • Name
    consentId
    Type
    string(uuid)
    Description

    The consent identification assigned to the created consent resource.

Headers

  • Name
    x-Request-ID
    Type
    string(uuid)
    Description

    ID of the request, unique to the call, as determined by the initiating part.

  • Name
    Certificate
    Type
    string
    Description

    The certificate used for signing the request, in base64 encoding. Must be contained if a signature is contained.

  • Name
    ClientId
    Type
    string
    Description

    The client identifier issued to the TPP.

  • Name
    Ocp-Apim-Subscription-Key
    Type
    string
    Description

    A unique identifier related to the registered merchant in the snappi API environment, available within the application's details.

Response attributes

  • Name
    scaStatus
    Type
    string
    Description

    Represents the status of Strong Customer Authentication (SCA) process. Possible values: received (0), psuIdentified (1), psuAuthenticated (2), scaMethodSelected (3), started (4), finalised (5), failed (6), exempted (7).

  • Name
    authenticationSchemes
    Type
    array
    Description

    The list of authentication schemes for the consent authorisation.

  • Name
    links
    Type
    object
    Description

    The links parameter provides links to additional resources or related information.

  • Name
    properties
    Type
    object
    Description

    The properties parameter contains the list of properties related to the consent authorisation.

  • Name
    statusCode
    Type
    integer
    Description

    The HTTP status code of the response.

  • Name
    tppMessages
    Type
    array
    Description

    The list of messages related to the TPP (Third-Party Provider) for the consent authorisation.It includes:

    • category: Indicates the category of the response. Possible values are ERROR (0) or WARNING (1).
    • code: Represents the error code of the response. Possible values: FORMATERROREnum (0), PARAMETERNOTCONSISTENTEnum (1), PARAMETERNOTSUPPORTEDEnum (2), SERVICEINVALIDEnum (3), RESOURCEUNKNOWNEnum (4), RESOURCEEXPIREDEnum (5), RESOURCEBLOCKEDEnum (6), TIMESTAMPINVALIDEnum (7), PERIODINVALIDEnum (8), SCAMETHODUNKNOWNEnum (9), CONSENTUNKNOWNEnum (10), SESSIONSNOTSUPPORTEDEnum (11), INVALIDTOTALAMOUNTEnum (12).
    • path: The path of the message.
    • text: The text of the message.

Request

GET
/v2/consents/confirmation-of-funds/{consentId}/status
curl -X GET /v2/consents/confirmation-of-funds/{consentId}/status \
-H 'Accept: application/json' \
-H 'X-Request-ID: string' \
-H 'Certificate: string' \
-H 'ClientId: string' \
-H 'Ocp-Apim-Subscription-Key: string'

Response examples

{
"scaStatus": 0
}

Responses

StatusDescription
200OK
400Bad Request
401Unauthorized
403Forbidden
404Not Found
405Method Not Allowed
406Not Acceptable
409Conflict
429Too Many Requests