For any question, we are one click away

Contact us

P2P solution

P2P transaction

P2P functionality helps you to provide users (current or potential customers) with the ability to send money to each other, also it allows you to accept transfers to your cards without sending your data to anyone and earn commissions by providing a service to a wide range of users.

The P2P service is a service available for customization and integration into third-party websites, mobile applications, as well as Internet and mobile banks.

Users have access to a complete list of operations, sending/receiving transfers, registering/authorizing in the service, managing saved cards.

An important feature of the P2P service is the ability to make transfers by phone number, even if the user is not yet registered in the system.

P2P transaction flow can be displayed in the following main scenarios:

Inputting card data on the gateway side

Interaction flow

sequenceDiagram participant C as Client participant OS as Online store participant PG as Payment Gateway participant ACS as ACS C ->> OS: 1. Forming an Order OS ->> PG: 2. Registering the Order PG -->> OS: 3. orderId, formUrl OS -->> C: 4. Redirecting to the card data collection form C ->> PG: 5. Receiving the card data collection form PG -->> C: 6. The card data collection form C ->> PG: 7. Sending the data in the filled in form PG ->> PG: 8. Checking if the card belongs to 3-D secure PG -->> C: 9. Redirecting the client to ACS C ->> ACS: 10. Receiving the authorization form ACS -->> C: 11. The authorization form C ->> ACS: 12. Filling in the form ACS -->> C: 13. Redirecting the client to the Payment Gateway C ->> PG: 14. Completing the secure payment PG ->> PG: 15. Making the payment PG -->> C: 16. Redirecting the client to the online store C ->> OS: 17. Getting the page with the result OS ->> PG: 18. Checking the status PG -->> OS: 19. Status of the Order OS -->> C: 20. Showing the result
  1. On the merchant's site (e.g. an online store) a cardholder requests to perform a P2P money transfer.
  2. The online store system registers the order in the Payment Gateway via registerP2P.do. The registration parameters used include the amount of the transfer, the currency, the order number in the merchant's system, and the return URL for the client.
  3. In response to the registration request, the Payment Gateway returns a unique identifier of the order in the payment system and the URL to redirect the client to the form for card data collection.
  4. The online store system passes the redirect URL received on step 3 to the client’s Web browser.
  5. The client’s Web browser opens the URL.
  6. At the specified URL, the client’s Web browser receives the form for card data collection.
  7. Client fills in the form and the data is sent to the Payment Gateway server.
  8. The system checks if the card belongs to 3-D Secure (SecureCode).
  9. The Gateway sends the redirect link to the Access Control Server (ACS) page of the issuing bank to the client’s Web browser (this step is necessary for the implementation of 3DS).
  10. The client’s Web browser requests the user authorization form from ACS.
  11. ACS sends the authorization form to the client’s Web browser.
  12. Client fills in the form and the information is sent to ACS.
  13. ACS processes the form and, regardless of the result, sends the redirect URL of the pages of the Payment Gateway to the client’s Web browser. The encrypted parameters of the authorization result are sent together with this URL.
  14. The client’s Web browser requests the Payment Gateway page when passing the encrypted parameters of the authorization result.
  15. Payment Gateway transfers the money.
  16. When the money is transferred, the Payment Gateway sends the return URL to the client’s Web browser (the URL was specified during the registration of the order by the online store on step 2).
  17. The client’s Web browser requests the results of the money transfer from the online store.
  18. The online store system requests the information about the order status from the payment gateway - getP2PStatus.do.
  19. Payment Gateway returns the status of the order.
  20. The online store system shows payment result to client.

Inputting card data on the online store side

Interaction flow

sequenceDiagram participant C as Client participant OS as Online store participant PG as Payment Gateway participant 3DSS as 3DS Server participant ACS as ACS C ->> OS: 1. Forming an Order OS ->> PG: 2. Registering the Order PG -->> OS: 3. Response to order registration OS -->> C: 4. Redirecting to the card data collection form C ->> OS: 5. Submitting the data OS ->> PG: 6. Requesting the fee amount PG -->> OS: 7. Receiving the fee amount OS ->> PG: 8. Request for a card-to-card transfer PG -> 3DSS: 9. Checking 3DSv2 availability PG -->> OS: 10. Response to the request for card-to-card transfer OS ->> 3DSS: 11. Calling a hidden iframe (threeDSMethodURLServer) opt [if threeDSMethodURL is in response] OS ->> ACS: 12. Calling a hidden iframe (threeDSMethodURL) end OS ->> PG: 13. Second request for transfer of funds PG ->> 3DSS: 14. Authentication request 3DSS ->> ACS: 15. Authentication request ACS -->> 3DSS: 16. Response to the authentication request 3DSS -->> PG: 17. Response to the authentication request PG -->> OS: 18. Response to the second order payment request opt [Redirection to ACS is required] OS ->> ACS: 19. CReq (ChallengeRequest) ACS -->> C: 20. HTML form to pass authentication C ->> ACS: 21. Confirmation of authenticity ACS ->> ACS: 22. Data processing ACS -> 3DSS: 23. Data exchange ACS -->> C: 24. Result of data processing and redirecting the client to the store page OS ->> PG: 25. finish3dsVer2Payment.do PG -->> OS: 26. Response to the request end OS ->> PG: 27. Order status request PG -->> OS: 28. Response to the order status request OS -->> C: 29. Showing the result
  1. A cardholder (client) interacts with the online store to create an order.
  2. The online store system registers the order in the Payment Gateway via registerP2P.do. The registration parameters used include the amount of the transfer, the currency, the order number in the merchant's system, and the return URL for the client.
  3. In response to the registration request, the Payment Gateway returns a unique identifier of the order in the payment system and the URL to redirect the client to the form for card data collection.
  4. The online store system passes the redirect URL received on step 3 to the client’s Web browser.
  5. Client fills in the form and submits the data.
  6. Optional. If the online store works with the fees, the online store sends to the Payment Gateway a request for the fee sum via verifyP2P.do / verifyP2PByBinding.do.
  7. Optional. Payment Gateway sends in response the fee amount.
  8. The online store sends a request for transfer of funds to the Payment Gateway via performP2P.do / performP2PByBinding.do.
    At this stage, the 3DS 2.0 operation is initiated.
  9. Payment Gateway checks on the 3DS server whether the client can authenticate using the 2.0 Protocol.
  10. Payment Gateway sends a response to the request made in the step 6. The response also returns the following parameters:
    • is3DSVer2 - 3DSv2 authentication capability flag (true/false)
    • threeDSServerTransId - transaction identifier assigned by the 3DS server
    • threeDSMethodURLServer - address of the 3DS server for collecting browser data
    • threeDSMethodURL - (optional) address of the ACS server for collecting browser data
    • threeDSMethodDataPacked - (optional) data for collecting browser data on ACS

    (See also request description).
  11. The online store calls threeDSMethodURLServer, in a separate "iframe" with the help of the POST method, using the value received from the response to the request for transfer of funds. This allows the 3DS server to collect data about the customer's browser.
  12. Optional step. If threeDSMethodURL and threeDSMethodDataPacked parameters were received in the response to the request for transfer of funds, the online store calls threeDSMethodURL in a separate iframe using the POST method.
  13. Transfer of funds - stage 2. The online store resends the request to make money transfer via performP2P.do / performP2PByBinding.do.
    You must pass threeDSServerTransId parameter - transaction identifier which was created by the 3DS server and returned in the step 10.
  14. Payment Gateway sends an authentication request to the 3DS server.
  15. 3DS server sends an authentication request (AReq) to the ACS server.
  16. ACS server sends an authentication request (ARes) response to the 3DS server.
  17. 3DS server sends the received data to the Payment Gateway.

    • If the client does not need to authenticate to the ACS, the Payment Gateway returns a response to the request for transfer of funds. In this case, go to the step 27 of this flow.
    • If the client needs to authenticate to the ACS, the Payment Gateway will send a response to the payment page with the data of redirection to the ACS.
  18. The payment page redirects to the acsUrl with the parameter creq=packedCReq.
  19. ACS displays the authentication page to the client ("challenge" page).
  20. Client is authenticated.
  21. ACS server verifies the authenticity of the authentication data.
  22. Data is exchanged between the ACS and 3DS servers and processing result is confirmed.
  23. The ACS server redirects the client to the store's page.
  24. The online store sends finish3dsVer2Payment.do request to the Payment Gateway.
  25. Payment Gateway sends the online store a response to the request made.
  26. The online store sends getP2PStatus.do to the Payment Gateway to find out the order status.
  27. Payment Gateway sends a response to the request made.
  28. The online store displays the result page to the client.

AFT transaction

AFT (Account Funding Transaction) - a special type of operations for debiting of funds for the purpose of replenishing the client's internal account in the merchant’s system or banking account in bank’s system (often used as an alternative to the purchase operation).

AFT transaction flow scenario is the same as for P2P transaction. The difference is that only data of the card to be debited is specified in AFT transaction.

OCT transaction

OCT (Original Credit Transaction) - a special type of transactions for crediting funds to the recipient in real time.

Interaction flow

sequenceDiagram participant C as Client participant OS as Online store participant PG as Payment Gateway C ->> OS: 1. Forming an Order OS ->> PG: 2. Registering the Order PG -->> OS: 3. orderId, formUrl OS -->> C: 4. Redirecting to the card data collection form C ->> PG: 5. Sending the data in the filled in form PG ->> PG: 6. Transfer of funds PG -->> C: 7. Redirecting the client to the online store C ->> OS: 8. Getting the page with the result OS ->> PG: 9. Checking the status PG -->> OS: 10. Status of the Order OS -->> C: 11. Showing the result
  1. A cardholder (client) interacts with the online store to create an order.
  2. The online store system registers the order in the Payment Gateway via registerP2P.do. The registration parameters used include the amount of the transfer, the currency, the order number in the merchant's system, and the return URL for the client.
  3. In response to the registration request, the Payment Gateway returns a unique identifier of the order in the payment system and the URL to redirect the client to the form for card data collection.
  4. The online store system passes the redirect URL received on step 3 to the client’s Web browser.
  5. Client fills in the form and the data is sent to the Payment Gateway server.
  6. Payment Gateway makes the transfer of funds via performP2P.do.
  7. When the money is transferred, the Payment Gateway sends the return URL to the client’s Web browser (the URL was specified during the registration of the order by the online store on step 2).
  8. The client’s Web browser requests the results of the money transfer from the online store.
  9. The online store system requests the information about the order status from the payment gateway - getP2PStatus.do.
  10. Payment Gateway returns the status of the order.
  11. The online store system shows payment result to the client.

API calls

P2P integrations require API calls to be signed. Information about request signatures is available in our API Guide.

P2P order registration

To register an order for the card-to-card money transfer, use registerP2P.do request.

Request parameters

Required Name Type Description
Mandatory

userName String [1..100] Merchant's API account login.
Mandatory

password String [1..200] Merchant's API account password.
Mandatory

orderNumber String [1..32] Order number (ID) in the merchant's system, must be unique for each order.
Mandatory

amount Integer [0..12] Payment amount in minor currency units (e.g. in cents etc.).
Mandatory

currency Integer [3] ISO 4217 encoded currency key. If not specified, the default value is used.
Mandatory

returnUrl String [1..512] The address to which the user will be redirected if the payment is successful. The address must be specified in full including the protocol used (for example, https://mybestmerchantreturnurl.com instead of mybestmerchantreturnurl.com). Otherwise, the user will be redirected to the address of the following type https://dev.bpcbt.com/payment/<merchant_address>.
Optional

failUrl String [1..512] The address to which the user is to be redirected in case of a failed payment. The address must be specified in full including the protocol used (for example, https://mybestmerchantreturnurl.com instead of mybestmerchantreturnurl.com). Otherwise, the user will be redirected to the address of the following type https://dev.bpcbt.com/payment/<merchant_address>.
Optional

orderDescription String [1..600] Order description passed to the payment gateway during the registration.
Optional

language String [2] ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
Supported languages: en,bg,de,fr,gr,hu,it,pl,ro,sp.
Optional

clientId String [0..255] Customer number (ID) in the merchant's system — up to 255 characters. Used to implement the functionality of stored-credential transactions. Can be returned in the response if the merchant is allowed to store credentials.
Specifying this parameter in stored-credential transactions is mandatory. Otherwise, a payment will be unsuccessful.
Optional

sessionTimeoutSecs Integer [1..9] Order lifetime in seconds. If the parameter is not specified, the value specified in the merchant settings or the default value (1200 seconds = 20 minutes) will be used. If the request contains expirationDate, the value of sessionTimeoutSecs is not taken into account.
Optional

sessionExpiredDate String Data and time of the order expiry. Format used: yyyy-MM-ddTHH:mm:ss.
If this parameter is not passed in the request, sessionTimeoutSecs is used to define the expiry of the order.
Optional

bindingId String [1..255] Identifier of an already existing stored credential. This is the card ID tokenized by the Gateway. Can be used only if the merchant has the permission to work with stored credentials. If this parameter is passed in this request, it means that:
  • This order can only be paid with a stored crediential;
  • The payer will be redirected to a payment page where only CVC entry is required.
Optional

creditBindingId String [0..255] Identifier of the stored credential of the card to be credited. It is used in card-to-card transfers when the recipient's card is known in advance. This parameter should first be passed in the request for transfer register (registerP2P.do - clientId parameter should also be passed here), then in the request for transfer funds by binding (performP2PByBinding.do - the value of creditBindingId parameter passed in registerP2P.do should be passed in bindingId parameter in toCard block).
Optional

transactionTypeIndicator String It is used in one-direction types of transaction: AFT, OCT.
  • AFT (Account Funding Transaction) - transfer from card to account;
  • OCT (Original Credit Transaction) - transaction from account to card.
There are such possible values:
  • G - Online gambling payout
  • A - Account to Account
  • D - Funds Disbursement
  • O - Loan payment
  • L - Card Bill Payment
  • T - Transfer to Own Staged Digital Wallet Account
  • F - Transfer to Own Stored Digital Wallet Account
  • P - Person to Person
Optional

features String Features of the order. As an example, below are the possible values.
  • VERIFY - If you specify this value in the order registration request, cardholder will be verified however they will not be charged any amount, so in this case amount parameter can be 0. Verification allows to make sure that a payment card is used by its legitimate owner, and further you can charge them without authentication (CVC, 3D-Secure). Even if some amount is passed in the request, the customer will not be charged if VERIFY feature is used. After a successful registration order status is changed to REVERSED. This value can be also used for storing the credential – in this case, the clientId parameter must be passed as well. Read more here.
  • FORCE_TDS - Force 3-D Secure payment. If a payment card does not support 3-D Secure, the transaction will fail.
  • FORCE_SSL - Force SSL payment (without 3-D Secure).
  • FORCE_FULL_TDS - After 3-D Secure authentication, PaRes status must be Y, which guarantees successful user authentication. Otherwise, the transaction will fail.
  • FORCE_CREATE_BINDING - passing this feature in the order registration request forcefully stores the credential. This functionality must be enabled by Merchant level permission in the Gateway. This value cannot be passed in a request with an existing bindingId or bindingNotNeeded = true (will cause validation error). When this feature is passed, the clientId parameter must be passed as well. If you pass both FORCE_CREATE_BINDING and VERIFY features, the order will be created for storing the credential ONLY (without payment).
Optional

params Object Fields for storing additional order information, must be passed as follows {"param":"value","param2":"value2"}.
These fields can be passed to the processing bank for further display in the bank registries.
By default orderNumber (order number) and orderDescription (order description) are passed. OrderDescription must not exceed 99 characters, do not use the following characters: %, +, end of line \r and line break \n).
To enable this functionality contact the bank.
Optional

email String Cardholder billing email.
Optional

feeInput String Fee amount in minimum currency units. Must be enabled by respective Merchant-level permission in the Gateway. If merchant has special permission and performs AFT (Account Funding Transaction) operations, the Merchant's commission comes in the registration request and is sent to the message for processing.
  • If feeInput is greater than 0, the externalFee attribute will be added to the TransactionModel, when the verifyP2P.do request is called, a verify request will not be sent to processing. The following tags will be added to the processing request, if they were passed in the additional parameters of the registration request: acc_number, contract, fio_sender, reference, fio_reciever.
  • If the feeInput is null or 0, the usual registerP2P.do request will be executed (the externalFee attribute will not be added, when the verifyP2P.do request is called, a verify request will be sent to processing).
Optional

billingPayerData Object A block with the client's registration data (address, postal code) necessary for passing the address verification within the AVS/AVV services. Mandatory if the feature is enabled for the merchant on Payment Gateway side. See nested parameters.

Below are the parameters of the billingPayerData block (data about the client registration address).

Required Name Type Description
Optional

billingCity String [0..50] The city registered on a specific card of the Issuing Bank.
Optional

billingCountry String [0..50] The country registered on a specific card of the Issuing Bank ( ISO 3166-1, numeric).
Optional

billingAddressLine1 String [0..50] The address registered on a specific card of the Issuing Bank. Line 1. Mandatory to be passed in order AVS verification works.
Optional

billingAddressLine2 String [0..50] The address registered on a specific card of the Issuing Bank. Line 2.
Optional

billingAddressLine3 String [0..50] The address registered on a specific card of the Issuing Bank. Line 3.
Optional

billingPostalCode String [0..9] Postal code registered on a specific card of the Issuing Bank. Mandatory to be passed in order AVS verification works.
Optional

billingState String [0..50] The state registered on a specific card of the Issuing Bank (ISO 3166-2).

Response parameters

Required Name Type Description
Mandatory

errorCode Integer [1..2] Information parameter in case of an error, which may have different code values:
  • 0 value - indicates success of processing;
  • another positive number value - indicates an error for more details of which errorMesage parameter must be inspected.
It also can be missing if the result has not caused any error.
Mandatory

errorMessage String [1..512] Information parameter that is an error description in a case of error occurance. errorMessage value can vary, so it should not be hardcoded.
Language of the description is set in language parameter of the request.
Optional

formUrl String [1..512] URL of the payment form, to which a customer will be redirected The URL is not returned if the registration of the order fails due to an error specified in errorCode.
Optional

orderId String [1..36] Order number in the payment gateway. Unique within the payment gateway.
Optional

orderNumber String [1..32] Order number (ID) in the merchant's system, must be unique for each order.

Examples

Request example

   curl -X POST 'https://dev.bpcbt.com/payment/rest/api/p2p/registerP2P.do' 
   -H 'Content-Type: application/json' 
   --data-raw '{
  "username":"test_user",
  "password":"test_user_password",
  "amount" : 50000,
  "currency" : "978",
  "returnUrl" : "https://mybestmerchantreturnurl.com",
  "orderNumber": "1"
}'

Request example of AFT operation

curl -X POST 'https://dev.bpcbt.com/payment/rest/api/p2p/registerP2P.do' -H 'Content-Type: application/json' --data-raw '{
  "username":"test_user",
  "password":"test_user_password",
  "amount" : 50000,
  "currency" : "978",
  "returnUrl" : "https://mybestmerchantreturnurl.com",
  "orderNumber": "12",
  "clientId": "122313",
  "bindingId": "59aaf552-cdae-70de-a092-8f8c00a9fba0",
  "transactionTypeIndicator": "A",
  "features":{
      "feature":["FEATURE_1", "FEATURE_2", .. "FEATURE_N"]
   }
}'

Request example of OCT operation

curl -X POST 'https://dev.bpcbt.com/payment/rest/api/p2p/registerP2P.do' -H 'Content-Type: application/json' --data-raw '{
  "username":"test_user",
  "password":"test_user_password",
  "amount" : 50000,
  "currency" : "978",
  "returnUrl" : "https://mybestmerchantreturnurl.com",
  "orderNumber": "12",
  "clientId": "122313",
  "creditBindingId": "99ef0cee-34fe-7312-ad7c-78bc00b3236a",
  "transactionTypeIndicator": "A",
  "features":{
      "feature":["FEATURE_1", "FEATURE_2", .. "FEATURE_N"]
   }
}'

Response example

{
  "errorCode": 0,
  "errorMessage": "Successful",
  "orderId": "0a4eaae8-653a-71a9-8259-46fc00a8ea58",
  "formUrl": "https://dev.bpcbt.com/payment/merchants/ecom/payment.html?mdOrder=0a4eaae8-653a-71a9-8259-46fc00a8ea58&language=en",
  "orderNumber": "2009"
}

Fee amount

To obtain the fee amount for the money transfer, use verifyP2P.do request.

The structure of the verifyP2P.do request assumes the existence of the fromCard block to pass the attributes of the card to be debited and the toCard block to pass the attributes of the card to be credited.

Depending on the business processes of the bank and the online store, the following options are possible when carrying out a card-to-card money transfer:

Request parameters

Required Name Type Description
Mandatory

userName String [1..100] Merchant's API account login.
Mandatory

password String [1..200] Merchant's API account password.
Mandatory

orderId String [1..36] Order number in the payment gateway. Unique within the payment gateway.
Optional

language String [2] ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
Supported languages: en,bg,de,fr,gr,hu,it,pl,ro,sp.
Optional

amount String [0..12] Payment amount in minor currency units.
This parameter is passed if the payer decides to change the transfer amount when carrying out the money transfer.
Conditional

fromCard Object A block with the attributes of the card to be debited. If debiting is done by a third-party system, this block must be absent. Otherwise, it is mandatory. See nested parameters.
Conditional

toCard Object A block with the attributes of the card to be credited. If crediting is done by a third-party system, this block must be absent. Otherwise, it is mandatory. See nested parameters.

The fromCard block (if debiting is done by a third-party system, this block must be absent) includes the following possible parameters:

Required Name Type Description
Mandatory

pan String [1..19] The number of the card to be debited.
Optional

cvc Integer CVC/CVV2 code on the back of a card to be debited.
Mandatory

expirationYear Integer The year of expiration of the card that is to be debited. The accepted values are from 2000 to 2200.
Mandatory

expirationMonth Integer The month of expiration of the card that is to be debited. Available values are as follows: 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12.
Mandatory

cardholderName String [1..26] The name of the holder of the card that is to be debited.
Conditional

seToken String Encrypted card data that replaces $PAN, $CVC, and $EXPIRY (or YYYY,MM) parameters. Must be passed if used instead of the card data.
The mandatory parameters for seToken string are timestamp, UUID, PAN, EXPDATE, MDORDER.
Click here more information about seToken generation.

The toCard block (if crediting is done by a third-party system, this block must be absent) consists of the following possible parameters:

Required Name Type Description
Mandatory

pan String [1..19] The number of the card to be credited.
Optional

cvc Integer CVC/CVV2 code on the back of a card that is to be credited.
Optional

expirationYear Integer The year of expiration of the card that is to be credited. The accepted values are from 2000 to 2200.
Optional

expirationMonth Integer The month of expiration of the card that is to be credited. Available values are as follows: 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12.
Optional

cardholderName String [1..26] The name of the holder of the card that is to be credited.
Conditional

seToken String Encrypted card data that replaces $PAN, $CVC, and $EXPIRY (or YYYY,MM) parameters. Must be passed if used instead of the card data.
The mandatory parameters for seToken string are timestamp, UUID, PAN, EXPDATE, MDORDER.
Click here more information about seToken generation.

Response parameters

Required Name Type Description
Mandatory

errorCode Integer [1..2] Information parameter in case of an error, which may have different code values:
  • 0 value - indicates success of processing;
  • another positive number value - indicates an error for more details of which errorMesage parameter must be inspected.
It also can be missing if the result has not caused any error.
Mandatory

errorMessage String [1..512] Information parameter that is an error description in a case of error occurance. errorMessage value can vary, so it should not be hardcoded.
Language of the description is set in language parameter of the request.

The feeDescriptionList block includes the following parameters:

Required Name Type Description
Optional

feeAmount Integer [1..12] Fee amount.
Optional

feeCurrency String [3] The ISO 4217 code of the fee currency.
Optional

feeDescription String [1..512] The description of the fee.

Examples

Request example

curl -X POST 'https://dev.bpcbt.com/payment/rest/api/p2p/verifyP2P.do' -H 'Content-Type: application/json' --data-raw '{
  "username":"test_user",
  "password":"test_user_password",
  "orderId": "0a4eaae8-653a-71a9-8259-46fc00a8ea58",
  "fromCard": {
    "cardholderName": "TEST CARDHOLDER",
    "cvc": "123",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "pan": "5000001111111115"
  },
  "toCard": {
    "pan": "4000001111111118"
  },    
  "amount" : 50000
}'

Response example

{
  "errorCode": 0,
  "errorMessage": "Successful",
  "feeDescriptionList: [ {
    "feeAmount": 500,
    "feeCurrency": "978",
    "feeDescription": "Acquirer fee"
  } ]
}

P2P transfer

To perform a card-to-card money transfer, use performP2P.do request.

The structure of the performP2P.do request assumes the presence of the fromCard block to pass the attributes of the card to be debited and the toCard block to pass the attributes of the card to be credited. Depending on the business processes of the bank and the online store, the following options are possible when carrying out a card-to-card money transfer:

Request parameters

Required Name Type Description
Mandatory

userName String [1..100] Merchant's API account login.
Mandatory

password String [1..200] Merchant's API account password.
Optional

language String [2] ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
Supported languages: en,bg,de,fr,gr,hu,it,pl,ro,sp.
Mandatory

orderId String [1..36] Order number in the payment gateway. Unique within the payment gateway.
Optional

ip String [1..39] Buyer's IP address. IPv6 is supported in all requests. (up to 39 characters).
Optional

email String The payer's email address.
Optional

amount String [0..12] Payment amount in minor currency units.
This parameter is passed if the payer decides to change the transfer amount when carrying out the money transfer.
Optional

agent_info.type Integer Agent type, the available values are:
  • 1 - bank paying agent;
  • 2 - bank paying subagent;
  • 3 - paying agent;
  • 4 - paying subagent;
  • 5 - designated agent;
  • 6 - commission agent;
  • 7 - other agent.
Optional

amountInput Integer [0..12] If the amount is specified in this parameter, the transfer will be made for this amount (regardless of the amount passed in the order registration request). The value should be specified in minor currency units.
Mandatory

params Object Fields for storing additional order information, must be passed as follows {"param":"value","param2":"value2"}.
These fields can be passed to the processing bank for further display in the bank registries.
By default orderNumber (order number) and orderDescription (order description) are passed. OrderDescription must not exceed 99 characters, do not use the following characters: %, +, end of line \r and line break \n).
To enable this functionality contact the bank.

The following customer data can be passed in the params object within a request for a card-to-card money transfer (the format of values depends on the data processing method used):
  • In the parameter called payerName — the name of the sender of money.
  • In the parameter called payerAddress — the address of the sender.
  • In the parameter called payerCity — the home city of the sender.
  • In the parameter called payerCountry — the country of the sender.
  • In the parameter called payerPostalCode — the postal code of the sender.
  • In a parameter called payerState — the region of the sender.
For the Visa payment system, in the request for a card-to-card money transfer, it is also necessary to pass the following information in the params parameter (format of values is determined by the data processing method used):
  • In the recipientName parameter — the name of the money recipient.
Optional

billingPayerData Object A block with the client's registration data (address, postal code) necessary for passing the address verification within the AVS/AVV services. Mandatory if the feature is enabled for the merchant on Payment Gateway side. See nested parameters.
Conditional

fromCard Object A block with the attributes of the card to be debited. If debiting is done by a third-party system, this block must be absent. Otherwise, it is mandatory. See nested parameters.
Conditional

toCard Object A block with the attributes of the card to be credited. If crediting is done by a third-party system, this block must be absent. Otherwise, it is mandatory. See nested parameters.
Optional

acsInIFrame Boolean Flag indicating that an iFrame version of the finish URL will be returned. Possible values are true or false. To enable this feature please contact support.

Below are the parameters of the billingPayerData block (data about the client registration address).

Required Name Type Description
Optional

billingCity String [0..50] The city registered on a specific card of the Issuing Bank.
Optional

billingCountry String [0..50] The country registered on a specific card of the Issuing Bank ( ISO 3166-1, numeric).
Optional

billingAddressLine1 String [0..50] The address registered on a specific card of the Issuing Bank. Line 1. Mandatory to be passed in order AVS verification works.
Optional

billingAddressLine2 String [0..50] The address registered on a specific card of the Issuing Bank. Line 2.
Optional

billingAddressLine3 String [0..50] The address registered on a specific card of the Issuing Bank. Line 3.
Optional

billingPostalCode String [0..9] Postal code registered on a specific card of the Issuing Bank. Mandatory to be passed in order AVS verification works.
Optional

billingState String [0..50] The state registered on a specific card of the Issuing Bank (ISO 3166-2).

The fromCard block (if debiting is done by a third-party system, this block must be absent) includes the following possible parameters:

Required Name Type Description
Mandatory

pan String [1..19] The number of the card to be debited.
Optional

cvc Integer CVC/CVV2 code on the back of a card to be debited.
Mandatory

expirationYear Integer The year of expiration of the card that is to be debited. The accepted values are from 2000 to 2200.
Mandatory

expirationMonth Integer The month of expiration of the card that is to be debited. Available values are as follows: 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12.
Mandatory

cardholderName String [1..26] The name of the holder of the card that is to be debited.
Conditional

seToken String Encrypted card data that replaces $PAN, $CVC, and $EXPIRY (or YYYY,MM) parameters. Must be passed if used instead of the card data.
The mandatory parameters for seToken string are timestamp, UUID, PAN, EXPDATE, MDORDER.
Click here more information about seToken generation.
Conditional

threeDsAuthResult Object A block with the data related to the result of 3 DS authentication when the merchant's MPI is used.
Is mandatory for transfer and AFT transactions with merchant's MPI.
See nested parameters.

When making payments using tokens (APPLE, SAMSUNG, GOOGLE), the fromCard block includes the following parameters instead of card details:

Required Name Type Description
Conditional

vendor String This parameter is used for payments made with tokens. It is the name of the payment service provider and can be one of the following: APPLE, GOOGLE, SAMSUNG.
This parameter must be passed together with the paymentToken parameter, which contains the actual payment token value.
This parameter cannot be used together with the following parameters : pan, cvc, expiry, bindingId, seToken.
Conditional

paymentToken String [1..8192] Token value of the vendor specified in vendor parameter (APPLE, GOOGLE, SAMSUNG). If vendor is specified, it must be passed.
This parameter cannot be used together with the following parameters : pan, cvc, expiry, bindingId, seToken.
Optional

decryptedToken Boolean Decrypted token for payments through vendors (ApplePay, GooglePay, etc.). Allowed values:
  • true – for the decrypted token;
  • false – for an encrypted token.

If this parameter is not passed, decryptedToken = false will be assumed by default.
Optional

protocolVersion String Protocol version as defined by Google for a paymentToken: ECv1 (by default) or ECv2

Below are the parameters of the threeDsAuthResult block (data related to 3 DS authentication).

Required Name Type Description
Optional

cavv String [0..200] Cardholder authentication value. The indicator is specified only after an order is paid and if the corresponding permission is enabled.
Optional

xid String [1..80] Electronic commerce indicator of the transaction. The indicator is specified only after an order has been paid and in case the corresponding permission is present.
Optional

eci Integer [1..4] Electronic commerce indicator. The indicator is specified only after an order has been paid and in case the corresponding permission is present. Below is the explanation of ECI codes.
  • ECI=1 or ECI=6 - merchant supports 3-D Secure, payment card does not support 3-D Secure, payment is processed based on CVV2/CVC code.
  • ECI=2 or ECI=5 - both merchant and payment card support 3-D Secure;
  • ECI=7 - merchant does not support 3-D Secure, payment is processed based on CVV2/CVC code.
Conditional

authenticationTypeIndicator String 3DS authentication type depending on ECI value.
Is mandatory for payment with merchant's API with 3DS 2 authentication.
Allowed values:
  • 0 - SSL (SSL authentication)
  • 3 - THREE_DS2_FULL (Strong customer authentication (SCA))
  • 4 - THREE_DS2_FRICTIONLESS (Risk based authentication(RBA))
  • 5 - THREE_DS2_ATTEMPT (3DS 2 authentication attempt)
Optional

threeDSProtocolVersion String 3DS protocol version. Possible values are "2.1.0", "2.2.0" for 3DS2.
If threeDSProtocolVersion is not passed in the request, then the default value will be used for 3D Secure authorization (2.1.0 - for 3DS 2).

The toCard block (if crediting is done by a third-party system, this block must be absent) consists of the following possible parameters:

Required Name Type Description
Mandatory

pan String [1..19] The number of the card to be credited.
Optional

cvc Integer CVC/CVV2 code on the back of a card that is to be credited.
Optional

expirationYear Integer The year of expiration of the card that is to be credited. The accepted values are from 2000 to 2200.
Optional

expirationMonth Integer The month of expiration of the card that is to be credited. Available values are as follows: 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12.
Optional

cardholderName String [1..26] The name of the holder of the card that is to be credited.
Conditional

seToken String Encrypted card data that replaces $PAN, $CVC, and $EXPIRY (or YYYY,MM) parameters. Must be passed if used instead of the card data.
The mandatory parameters for seToken string are timestamp, UUID, PAN, EXPDATE, MDORDER.
Click here more information about seToken generation.

The following parameters are also passed during the authentication via the 3DS 2.0 protocol:

Required Name Type Description
Optional

threeDSServerTransId String Transaction identifier created on 3DS Server.
Optional

threeDSVer2FinishUrl String URL where Customer should be redirected after authentication on ACS Server.
Optional

threeDSMethodNotificationUrl String URL where notification about authentication on ACS Server should be sent to.

Response parameters

Required Name Type Description
Mandatory

errorCode Integer [1..2] Information parameter in case of an error, which may have different code values:
  • 0 value - indicates success of processing;
  • another positive number value - indicates an error for more details of which errorMesage parameter must be inspected.
It also can be missing if the result has not caused any error.
Optional

errorMessage String [1..512] Information parameter that is an error description in a case of error occurance. errorMessage value can vary, so it should not be hardcoded.
Language of the description is set in language parameter of the request.
Optional

info String The result of an attempt to transfer funds.

The value in case of a successful transfer: "Your payment has been processed, redirecting...".

The value in case of an error: "Redirecting..."
Optional

acsUrl String [1..512] In a successful response in case of a 3D-Secure payment. The URL address for redirecting to ACS. For details see Redirect to ACS.
Optional

paReq String [1..255] In a successful response in case of a 3D-Secure payment. PAReq (Payment Authentication Request) - a message that should be sent to ACS together with redirect. This message contains the Base64-encoded data necessary for the cardholder authentication. For details see Redirect to ACS.
Optional

termUrl String [1..512] In a successful response in case of a 3D-Secure payment. URL address for redirecting the client after interaction with the ACS for the payment completion.
Optional

acsInIFrame Boolean Flag indicating that an iFrame version of the finish URL will be returned. Possible values are true or false. To enable this feature please contact support.

When authenticating via the 3DS 2.0 protocol, the following parameters are returned during the initial request:

Required Name Type Description
Mandatory

is3DSVer2 Boolean Possible values: true or false. Flag showing that payment uses 3DS 2.0.
Mandatory

threeDSServerTransId String Transaction identifier created on 3DS Server.
Optional

threeDSMethodUrl String URL of ACS Server for gathering browser data.
Mandatory

threeDSMethodUrlServer String URL of 3DS Server for gathering browser data to be included in the AReq (Authentication Request) from 3DS Server to ACS Server.
Optional

threeDSMethodDataPacked String Base-64-encoded data of CReq (Challenge Response) to be sent to ACS Server.
Optional

threeDSMethodURLServerDirect String URL of 3dsmethod.do for executing the 3DS method on 3DS Server via Payment Gateway (subject to respective Merchant-level permission).

Below are the parameters to be present in the response, after a repeated request for the payment and the need to redirect the client to the ACS during the authentication via the 3DS 2.0 protocol:

Required Name Type Description
Conditional*

acsUrl String [1..512] In a successful response in case of a 3D-Secure payment. The URL address for redirecting to ACS. For details see Redirect to ACS.
Conditional*

packedCReq String Packed challenge request data. This value should be used as the ACS link creq parameter (acsUrl) to redirect the client to the ACS.

* Mandatory, if redirect to the ACS is needed.

Examples

Request example

Example of the first request:

curl -X POST 'https://dev.bpcbt.com/payment/rest/api/p2p/performP2P.do' -H 'Content-Type: application/json' --data-raw '{
  "username":"test_user",
  "password":"test_user_password",
  "orderId" : "38b7a9e0-7cfa-46f7-8655-f206a8898e7a",
  "amount" : 50000,
  "fromCard": {
    "vendor": "APPLE",
    "paymentToken": "eyJkZXZpY2VNYW51ZmFjdHVyZXJJZGVudGlmaWVyIjoiMDUwMTEwMDMwMjczIiwiY3VycmVuY3lDb2RlIjoiOTc4IiwiYXBwbGljYXRpb25FeHBpcmF0aW9uRGF0ZSI6IjI3MDEzMSIsInBheW1lbnREYXRhIjp7Im9ubGluZVBheW1lbnRDcnlwdG9ncmFtIjoiQUc5WW5Pak1YOUJXQUFSaElJOFBBb0FCRkE9PSJ9LCJwYXltZW50RGF0YVR5cGUiOiIzRFNlY3VyZSIsInRyYW5zYWN0aW9uQW1vdW50IjoxMDAsImFwcGxpY2F0aW9uUHJpbWFyeUFjY291bnROdW1iZXIiOiI1NTU1NTU1NTU1NTU1NTk5In0=",
    "decryptedToken":true,
    "protocolVersion":"ECv1"
  },
  "toCard" : {
    "pan" : "4111111111111111",
    "cvc" : "123",
    "expirationYear" : "2030",
    "expirationMonth" : "12",
    "cardholderName" : "Name Surname"
  },
  "params" : [
        {"name" : "recipientName", "Name" : "Surname"},
        {"name" : "payerName", "value" : "Name1 Surname1"},
        {"name" : "payerCity", "value" : "City"},
        {"name" : "payerCountry", "value" : "Country"},
        {"name" : "payerPostalCode", "value" : "777777"},
        {"name" : "payerState", "value" : "State"},
        {"name" : "payerAddress", "value" : "street, 18"
  },    
 ] 
}

Example of the second request:

curl -X POST 'https://dev.bpcbt.com/payment/rest/api/p2p/performP2P.do' -H 'Content-Type: application/json' --data-raw '{
  "username":"test_user",
  "password":"test_user_password",
  "orderId": "0a4eaae8-653a-71a9-8259-46fc00a8ea58",
  "fromCard": {
    "cardholderName": "TEST CARDHOLDER",
    "cvc": "123",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "pan": "5000001111111115"
  },
  "toCard": {
    "pan": "4111111111111111"
  },    
  "amount" : 50000,
  "params" : [
        {"name" : "recipientName", "Name" : "Surname"},
        {"name" : "payerName", "value" : "Name1 Surname1"},
        {"name" : "payerCity", "value" : "City"},
        {"name" : "payerCountry", "value" : "Country"},
        {"name" : "payerPostalCode", "value" : "777777"},
        {"name" : "payerState", "value" : "State"},
        {"name" : "payerAddress", "value" : "street, 18"
  "threeDSServerTransId" : "3afc168a-94b4-4eb3-8e2e-80f6c186669d",
  "threeDSVer2FinishUrl" : "https://example.com/acs2/acs/3dsMethod"
}'

Response example

Example of the response to the first request:

{
  "errorCode": 0,
  "is3DSVer2": true,
  "threeDSServerTransId": "3afc168a-94b4-4eb3-8e2e-80f6c186669d",
  "threeDSMethodURL": "https://example.com/acs2/acs/3dsMethod",
  "threeDSMethodURLServer": "https://example.com/3dsserver/api/v1/client/gather?threeDSServerTransID=3afc168a-94b4-4eb3-8e2e-80f6c186669d",
  "threeDSMethodDataPacked": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9jb21tb24wMy50c3QucmJzdGVzdC5ydS8zZHNzZXJ2ZXIvYXBpL3YxL2Fjcy9ub3RpZmljYXRpb24_dGhyZWVEU1NlcnZlclRyYW5zSUQ9M2FmYzE2OGEtOTRiNC00ZWIzLThlMmUtODBmNmMxODY2NjlkIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiIzYWZjMTY4YS05NGI0LTRlYjMtOGUyZS04MGY2YzE4NjY2OWQifQ"
}

Example of the response to the second request:

{
  "errorCode": 0,
  "info": "Your order is proceeded, redirecting...",
  "acsUrl": "https://example.com/acs2/acs/creq",
  "is3DSVer2": true,
  "packedCReq": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjNhZmMxNjhhLTk0YjQtNGViMy04ZTJlLTgwZjZjMTg2NjY5ZCIsIm1lc3NhZ2VUeXBlIjoiQ1JlcSIsIm1lc3NhZ2VWZXJzaW9uIjoiMi4xLjAiLCJhY3NUcmFuc0lEIjoiOWM3NTkxMmEtZTg0NC00ODgyLWI5YzctYzZmYmMzNjIyNGQ3IiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0"
}

P2P transfer status

To obtain the status of a registered P2P order, use getP2PStatus.do request.

Request parameters

Required Name Type Description
Mandatory

userName String [1..100] Merchant's API account login.
Mandatory

password String [1..200] Merchant's API account password.
Optional

language String [2] ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
Supported languages: en,bg,de,fr,gr,hu,it,pl,ro,sp.
Conditional

orderId String [1..36] Order number in the payment gateway. Unique within the payment gateway.
Conditional

orderNumber String [1..32] Order number (ID) in the merchant's system, must be unique for each order.

Response parameters

Required Name Type Description
Mandatory

errorCode Integer [1..2] Information parameter in case of an error, which may have different code values:
  • 0 value - indicates success of processing;
  • another positive number value - indicates an error for more details of which errorMesage parameter must be inspected.
It also can be missing if the result has not caused any error.
Mandatory

errorMessage String [1..512] Information parameter that is an error description in a case of error occurance. errorMessage value can vary, so it should not be hardcoded.
Language of the description is set in language parameter of the request.
Optional

orderStatus Integer The value of this parameter specifies the status of the order in the payment gateway. It is missing if the order has not been found. Below is the list of available values:
  • 0 - order was registered but not paid;
  • 2 - order amount is fully authorized;
  • 3 - authorization reversed;
  • 5 - access control server of the issuing bank initiated authorization procedure;
  • 6 - authorization declined;
Optional

orderNumber String [1..32] Order number (ID) in the merchant's system, must be unique for each order.
Optional

panMaskedFrom String [1..19] The masked number of the card to be debited.
Optional

panMaskedTo String [1..19] The masked number of the card to be credited.
Optional

amount Integer [0..12] Payment amount in minor currency units (e.g. in cents etc.).
Optional

currency Integer [3] ISO 4217 encoded currency key. If not specified, the default value is used.
Optional

creationDate Integer Date of order registration.
Optional

orderDescription String [1..600] Order description passed to the payment gateway during the registration.
Optional

ip String [1..39] Buyer's IP address. IPv6 is supported in all requests. (up to 39 characters).
Mandatory

resultCode Integer Error code on the request execution. Available values:
  • 0 - in case of success;
  • 1 - in case of an error.
Optional

orderParams Object An object with the merchant attributes. More than one orderParams object can be presented in the response.
The object must be passed as follows: {"param":"value","param2":"value2"}.
Optional

operationList Object Object containing information on the transactions completed in the order. More than one operationList object can be present in the response.
The parameters that can be passed here are described below.
Optional

binding String Identifier of a stored credential (if it has been already created). This parameter is returned only if the getP2PStatus version is 3 or higher.

Below are possible parameters of the operationList block.

Required Name Type Description
Optional

operationType String Transaction type. The following values are available:
  • P2P_VERIFY - requests the fee amount;
  • P2P_DEBIT - debits the money;
  • P2P_CREDIT - credits the money;
  • P2P_DEBIT_REVERSAL - debit cancellation;
  • P2P_CREDIT_REVERSAL - credit cancellation;
  • P2P_TRANSFER - card-to-card money transfer;
  • P2P_TRANSFER_REVERSAL - automatic refund if an error occurs during the transfer.
    Optional

    amount Integer [0..12] Payment amount in minor currency units (e.g. in cents etc.).
    Optional

    currency Integer [3] ISO 4217 encoded currency key. If not specified, the default value is used.
    Optional

    datetime String Date and time of the transaction.
    Optional

    resultCode Integer Error code on the request execution. Available values:
    • 0 - in case of success;
    • 1 - in case of an error.
    Optional

    resultCodeDescription String [1..512] Description of the transaction error code.
    Optional

    maskedPan String [1..19] Masked number of the card or token used for the payment.
    Optional

    cardholderName String [1..26] Cardholder's name (if available).
    Optional

    refNum String [12] Unique identification number that is assigned to the operation on its completion.

    Examples

    Request example

    curl -X POST 'https://dev.bpcbt.com/payment/rest/api/p2p/getP2PStatus.do' -H 'Content-Type: application/json' --data-raw '{ 
      "username": "test_user",
      "password": "test_user_password",
      "orderId" : "0a4eaae8-653a-71a9-8259-46fc00a8ea58"
    }'
    

    Response example

    {
      "orderStatus": 0,
      "errorCode": 0,
      "errorMessage": "Successful",
      "orderNumber": "2009",
      "amount": 50000,
      "currency": "978",
      "creationDate": 1674137044330,
      "orderParams": [],
      "operationList": [],
      "resultCode": 0
    }
    

    Stored-credential P2P transfer

    To perform a card-to-card transfer by binding, use performP2PByBinding.do request.

    Request parameters

    Required Name Type Description
    Mandatory

    userName String [1..100] Merchant's API account login.
    Mandatory

    password String [1..200] Merchant's API account password.
    Optional

    language String [2] ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
    Supported languages: en,bg,de,fr,gr,hu,it,pl,ro,sp.
    Optional

    ip String [1..39] Buyer's IP address. IPv6 is supported in all requests. (up to 39 characters).
    Optional

    email String The payer's email address.
    Optional

    type String In the case of a money transfer with data on only one card, it is necessary to pass the corresponding value in this parameter:
    • WITHOUT_FROM_CARD - without indication of the card to be debited;
    • WITHOUT_TO_CARD - without indication of the card to be credited.
    If an ordinary card-to-card money transfer is concerned the following value is to be passed here:
    • STANDARD
    Mandatory

    orderId String [1..36] Order number in the payment gateway. Unique within the payment gateway.
    Optional

    amountInput Integer [0..12] If the amount is specified in this parameter, the transfer will be made for this amount (regardless of the amount passed in the order registration request). The value should be specified in minor currency units.
    Optional

    params Object Fields for storing additional order information, must be passed as follows {"param":"value","param2":"value2"}.
    These fields can be passed to the processing bank for further display in the bank registries.
    By default orderNumber (order number) and orderDescription (order description) are passed. OrderDescription must not exceed 99 characters, do not use the following characters: %, +, end of line \r and line break \n).
    To enable this functionality contact the bank.

    The following customer data can be passed in the params object within a request for a card-to-card money transfer (the format of values depends on the data processing method used):
    • In the parameter called payerName — the name of the sender of money.
    • In the parameter called payerAddress — the address of the sender.
    • In the parameter called payerCity — the home city of the sender.
    • In the parameter called payerCountry — the country of the sender.
    • In the parameter called payerPostalCode — the postal code of the sender.
    • In a parameter called payerState — the region of the sender.
    For the Visa payment system, in the request for a card-to-card money transfer, it is also necessary to pass the following information in the params parameter (format of values is determined by the data processing method used):
    • In the recipientName parameter — the name of the money recipient.
    Conditional

    fromCard Object A block with the attributes of the card to be debited. If debiting is done by a third-party system, this block must be absent. Otherwise, it is mandatory. See nested parameters.
    Conditional

    toCard Object A block with the attributes of the card to be credited. If crediting is done by a third-party system, this block must be absent. Otherwise, it is mandatory. See nested parameters.

    The fromCard block (if debiting is done by a third-party system, this block must be absent) includes the following possible parameters:

    Required Name Type Description
    Optional

    bindingId String [1..255] Identifier of the credentials stored when paying for the order or used for payment. Available only if the merchant is allowed to store credentials.
    Mandatory

    pan String [1..19] The number of the card to be debited.
    Optional

    cvc Integer CVC/CVV2 code on the back of a card to be debited.
    Mandatory

    expirationYear Integer The year of expiration of the card that is to be debited. The accepted values are from 2000 to 2200.
    Mandatory

    expirationMonth Integer The month of expiration of the card that is to be debited. Available values are as follows: 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12.
    Mandatory

    cardholderName String [1..26] The name of the holder of the card that is to be debited.
    Optional

    seToken String Encrypted card data that replaces $PAN, $CVC, and $EXPIRY (or YYYY,MM) parameters. Must be passed if used instead of the card data.
    The mandatory parameters for seToken string are timestamp, UUID, bindingId, MDORDER. Click here for more information about seToken generation.

    The toCard block (if crediting is done by a third-party system, this block must be absent) consists of the following possible parameters:

    Required Name Type Description
    Optional (

    bindingId String [1..255] Identifier of the credentials stored when paying for the order or used for payment. Available only if the merchant is allowed to store credentials.
    Mandatory

    pan String [1..19] The number of the card to be credited.
    Optional

    cvc Integer CVC/CVV2 code on the back of a card that is to be credited.
    Optional

    expirationYear Integer The year of expiration of the card that is to be credited. The accepted values are from 2000 to 2200.
    Optional

    expirationMonth Integer The month of expiration of the card that is to be credited. Available values are as follows: 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12.
    Optional

    cardholderName String [1..26] The name of the holder of the card that is to be credited.

    Below are the parameters of the billingPayerData block (data about the client registration address).

    Required Name Type Description
    Optional

    billingCity String [0..50] The city registered on a specific card of the Issuing Bank.
    Optional

    billingCountry String [0..50] The country registered on a specific card of the Issuing Bank ( ISO 3166-1, numeric).
    Optional

    billingAddressLine1 String [0..50] The address registered on a specific card of the Issuing Bank. Line 1. Mandatory to be passed in order AVS verification works.
    Optional

    billingAddressLine2 String [0..50] The address registered on a specific card of the Issuing Bank. Line 2.
    Optional

    billingAddressLine3 String [0..50] The address registered on a specific card of the Issuing Bank. Line 3.
    Optional

    billingPostalCode String [0..9] Postal code registered on a specific card of the Issuing Bank. Mandatory to be passed in order AVS verification works.
    Optional

    billingState String [0..50] The state registered on a specific card of the Issuing Bank (ISO 3166-2).

    The following parameters are also passed during the authentication via the 3DS 2.0 protocol:

    Mandatory Name Type Description
    Optional

    threeDSServerTransId String Transaction identifier created on 3DS Server.
    Optional

    threeDSVer2FinishUrl String URL where Customer should be redirected after authentication on ACS Server.
    Optional

    threeDSMethodNotificationUrl String URL where notification about authentication on ACS Server should be sent to.

    Response parameters

    Required Name Type Description
    Mandatory

    errorCode Integer [1..2] Information parameter in case of an error, which may have different code values:
    • 0 value - indicates success of processing;
    • another positive number value - indicates an error for more details of which errorMesage parameter must be inspected.
    It also can be missing if the result has not caused any error.
    Mandatory

    errorMessage String [1..512] Information parameter that is an error description in a case of error occurance. errorMessage value can vary, so it should not be hardcoded.
    Language of the description is set in language parameter of the request.
    Optional

    info String The result of an attempt to transfer funds.

    The value in case of a successful transfer: "Your payment has been processed, redirecting...".

    The value in case of an error: "Redirecting..."
    Optional

    acsUrl String [1..512] In a successful response in case of a 3D-Secure payment. The URL address for redirecting to ACS. For details see Redirect to ACS.
    Optional

    paReq String [1..255] In a successful response in case of a 3D-Secure payment. PAReq (Payment Authentication Request) - a message that should be sent to ACS together with redirect. This message contains the Base64-encoded data necessary for the cardholder authentication. For details see Redirect to ACS.
    Optional

    termUrl String [1..512] In a successful response in case of a 3D-Secure payment. The URL address to which ACS redirects the cardholder after authentication. For details see Redirect to ACS.

    When authenticating via the 3DS 2.0 protocol, the following parameters are returned during the initial request:

    Required Name Type Description
    Mandatory

    is3DSVer2 Boolean Possible values: true or false. Flag showing that payment uses 3DS 2.0.
    Mandatory

    threeDSServerTransId String Transaction identifier created on 3DS Server.
    Optional

    threeDSMethodUrl String URL of ACS Server for gathering browser data.
    Mandatory

    threeDSMethodUrlServer String URL of 3DS Server for gathering browser data to be included in the AReq (Authentication Request) from 3DS Server to ACS Server.
    Optional

    threeDSMethodDataPacked String Base-64-encoded data of CReq (Challenge Response) to be sent to ACS Server.
    Optional

    threeDSMethodURLServerDirect String URL of 3dsmethod.do for executing the 3DS method on 3DS Server via Payment Gateway (subject to respective Merchant-level permission).

    Below are the parameters to be present in the response, after a repeated request for the payment and the need to redirect the client to the ACS during the authentication via the 3DS 2.0 protocol:

    Required Name Type Description
    Conditional*

    acsUrl String [1..512] In a successful response in case of a 3D-Secure payment. The URL address for redirecting to ACS. For details see Redirect to ACS.
    Conditional*

    packedCReq String Packed challenge request data. This value should be used as the ACS link creq parameter (acsUrl) to redirect the client to the ACS.

    * Mandatory if the redirect to the ACS is needed.

    Examples

    Request example

    curl -X POST 'https://dev.bpcbt.com/payment/rest/api/p2p/performP2PByBinding.do' -H 'Content-Type: application/json' --data-raw '{ 
      "amountInput" : 1000,
      "bindingId" : "03e9492a-536c-7ab4-85e6-b44000f26b04",
      "fromCard" : {
         "seToken": "ofVx1r3aIJ3Mlx3nkfeOIJgFOnwfsgFK+V6Yzm+KxJgsq19l74GChhX0We/LEFq78Rhn9uFAEZGdeyDhnIc/KfuvObf0EzoDA65Uj1Z8FjwWyjnEwTBHZL4KmdFBCSk8jLxHt70mXwyjiHYyCVH1fT/UVOnsrkZVGrqmEG4MTi5dX9Znzf24DwRg4iezvdT8vf0dUW5lJdvY1tgOsOnBulwy6kH/YbHVsnR6yxO6d6IsdnT5f8PxaB+7ZyUqgrd6VA88FGJKJgdoxk4721pqKSG5dYroLJG96s23EDJ2Hpi4e9wU2rP7E6dlFw+qzATqX/eaJbaQ9eakkdMWnkj7aQ=="
      },
      "toCard": {
            "cardholderName": "NAME SURNAME",
            "cvc": "123",
            "expirationMonth": 12,
            "expirationYear": 2024,
            "pan": "5555555555555599"
      },
      "orderId" : "3dbaf8bb-1d68-76b3-b4e6-784700f26b04",
      "password" : "test_user_password",
      "type" : "WITHOUT_TO_CARD",
      "username" : "test_user"
    }'
    

    Response example

    {
      "errorCode" : 0,
      "errorMessage" : "Successful",
      "info" : "Your order is proceeded, redirecting...",
      "redirect" : "https://example.com/?orderId=47743354-be15-7c70-b9ef-4bfc482e68dc&lang=en",
      "is3DSVer2" : false
    }
    

    Request example with authentication via the 3DS 2.0 protocol

    Example of the first request:

    curl -X POST 'https://dev.bpcbt.com/payment/rest/api/p2p/performP2PByBinding.do' -H 'Content-Type: application/json' --data-raw '{ 
      "amountInput" : 1000,
      "currency" : "978",
      "fromCard" : {
        "bindingId" : "fd3afc57-c6d0-4e08-aaef-1b7cfeb093dc",
        "cvc" : "123"
      },
      "orderId" : "38b7a9e0-7cfa-46f7-8655-f206a8898e7a",
      "password" : "test_user_password",
      "type" : "WITHOUT_TO_CARD",
      "username" : "test_user",
      "params" : {
        "name" : "payerAddress",
        "value" : "payer Address"
      }
    }'
    

    Example of the second request:

    curl -X POST 'https://dev.bpcbt.com/payment/rest/api/p2p/performP2PByBinding.do' -H 'Content-Type: application/json' --data-raw '{ 
      "amountInput" : 1000,
      "currency" : "978",
      "fromCard" : {
        "bindingId" : "fd3afc57-c6d0-4e08-aaef-1b7cfeb093dc",
        "cvc" : "123"
      },
      "orderId" : "38b7a9e0-7cfa-46f7-8655-f206a8898e7a",
      "password" : "test_user_password",
      "type" : "WITHOUT_TO_CARD",
      "username" : "test_user",
      "params" : {
        "name" : "payerAddress",
        "value" : "payer Address"
      },
      "threeDSServerTransId" : "f44d6d21-1874-45a5-aeb0-1c710dd6e134",
      "threeDSVer2FinishUrl" : "https://example.com/acs2/acs/3dsMethod"
    }'
    

    Response example with authentication via the 3DS 2.0 protocol

    Example of the response to the first request:

    {
      "errorCode": 0,
      "is3DSVer2": true,
      "threeDSServerTransId": "f44d6d21-1874-45a5-aeb0-1c710dd6e134",
      "threeDSMethodURLServer": "https://example.com/3dsserver/api/v1/client/gather?threeDSServerTransID=f44d6d21-1874-45a5-aeb0-1c710dd6e134",
    }
    

    Example of the response to the second request:

    {
      "errorCode": 0,
      "info": "Your order is proceeded, redirecting...",
      "acsUrl": "https://example.com/acs2/acs/creq",
      "is3DSVer2": true,
      "packedCReq" : "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjVmMzEyMjdlLTljZmQtNDQwYi1hNDNjLTE4NjljMzNhNGI5YiIsImFjc1RyYW5zSUQiOiI5YTQyYzQ4ZC1hNWRiLTQ3NjEtYmI4Mi05ZmY5MmM0NzZiM2QiLCJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDQiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIn0="
    }
    

    Stored-credential P2P fee amount

    To get the amount of commission when transferring funds by a stored-credential transaction, use the verifyP2PByBinding.do request.

    Request parameters

    Required Name Type Description
    Mandatory

    userName String [1..100] Merchant 's API account login. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter.
    Mandatory

    password String [1..200] Merchant's API account password.
    Optional

    language String [2] ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
    Supported languages: en,bg,de,fr,gr,hu,it,pl,ro,sp.
    Mandatory

    orderId String [1..36] Order number in the payment gateway. Unique within the payment gateway.
    Conditional

    fromCard Object A block with the attributes of the card to be debited. If debiting is done by a third-party system, this block must be absent. Otherwise, it is mandatory. See nested parameters.
    Conditional

    toCard Object A block with the attributes of the card to be credited. If crediting is done by a third-party system, this block must be absent. Otherwise, it is mandatory. See nested parameters.

    The fromCard block (if debiting is done by a third-party system, this block must be absent) includes the following possible parameters:

    Required Name Type Description
    Optional (

    bindingId String [1..255] Identifier of the credentials stored when paying for the order or used for payment. Available only if the merchant is allowed to store credentials.
    Mandatory

    pan String [1..19] The number of the card to be debited.
    Optional

    cvc Integer CVC/CVV2 code on the back of a card to be debited.
    Mandatory

    expirationYear Integer The year of expiration of the card that is to be debited. The accepted values are from 2000 to 2200.
    Mandatory

    expirationMonth Integer The month of expiration of the card that is to be debited. Available values are as follows: 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12.
    Mandatory

    cardholderName String [1..26] The name of the holder of the card that is to be debited.
    Optional

    seToken String Encrypted card data that replaces $PAN, $CVC, and $EXPIRY (or YYYY,MM) parameters. Must be passed if used instead of the card data.
    The mandatory parameters for seToken string are timestamp, UUID, bindingId, MDORDER. Click here for more information about seToken generation.

    The toCard block (if crediting is done by a third-party system, this block must be absent) consists of the following possible parameters:

    Required Name Type Description
    Optional (

    bindingId String [1..255] Identifier of the credentials stored when paying for the order or used for payment. Available only if the merchant is allowed to store credentials.
    Mandatory

    pan String [1..19] The number of the card to be credited.
    Optional

    cvc Integer CVC/CVV2 code on the back of a card that is to be credited.
    Optional

    expirationYear Integer The year of expiration of the card that is to be credited. The accepted values are from 2000 to 2200.
    Optional

    expirationMonth Integer The month of expiration of the card that is to be credited. Available values are as follows: 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12.
    Optional

    cardholderName String [1..26] The name of the holder of the card that is to be credited.

    Response parameters

    Required Name Type Description
    Mandatory

    errorCode Integer [1..2] Information parameter in case of an error, which may have different code values:
    • 0 value - indicates success of processing;
    • another positive number value - indicates an error for more details of which errorMesage parameter must be inspected.
    It also can be missing if the result has not caused any error.
    Mandatory

    errorMessage String [1..512] Information parameter that is an error description in a case of error occurance. errorMessage value can vary, so it should not be hardcoded.
    Language of the description is set in language parameter of the request.
    Optional

    feeAmount Integer [1..12] Fee amount.
    Optional

    feeCurrency String [3] The ISO 4217 code of the fee currency.
    Optional

    feeDescription String [1..512] The description of the fee.

    Examples

    Request example

    curl --location --request POST 'https://dev.bpcbt.com/payment/rest/api/p2p/verifyP2PByBinding.do' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "username": "test_user",
        "password": "test_user_password",
        "orderId": "fa71bf70-7c81-484e-a6fc-7db7e4283b2a",
        "bindingId": "4d792471-cee0-742c-922d-a265072e6148",
        "fromCard": {
            "seToken": "ofVx1r3aIJ3Mlx3nkfeOIJgFOnwfsgFK+V6Yzm+KxJgsq19l74GChhX0We/LEFq78Rhn9uFAEZGdeyDhnIc/KfuvObf0EzoDA65Uj1Z8FjwWyjnEwTBHZL4KmdFBCSk8jLxHt70mXwyjiHYyCVH1fT/UVOnsrkZVGrqmEG4MTi5dX9Znzf24DwRg4iezvdT8vf0dUW5lJdvY1tgOsOnBulwy6kH/YbHVsnR6yxO6d6IsdnT5f8PxaB+7ZyUqgrd6VA88FGJKJgdoxk4721pqKSG5dYroLJG96s23EDJ2Hpi4e9wU2rP7E6dlFw+qzATqX/eaJbaQ9eakkdMWnkj7aQ=="
        },
        "toCard": {
            "cardholderName": "NAME SURNAME",
            "cvc": "123",
            "expirationMonth": 12,
            "expirationYear": 2024,
            "pan": "5555555555555599"
        },
        "amount": 1000,
        "currency": "978",
        "clientId": "123",
    }'
    

    Response example

    {
      "errorCode" : 0,
      "errorMessage" : "Successful",
      "feeDescriptionList" : [ {
        "feeAmount" : 10,
        "feeCurrency" : "978",
        "feeDescription" : "Acquirer fee"
      } ]
    }
    
    Categories:
    eCommerce API V1
    Categories
    Search results