P2P Transfer

Overview
The P2P Transfer API allows for seamless peer-to-peer transactions, providing a secure and efficient way for users to transfer funds. The API consists of three main endpoints: retrieving receiver card information, creating a P2P transaction, and confirming the transaction.

Before sending a request

• Make sure you have subscribe api-key provided by Paylov
• Include the API key in the request headers

1. Get receiver card info by card number

Description: Retrieves the information of the receiver's card based on the provided card number.

Endpoint details

Method: POST
URL: BASE_URL/merchant/p2p/receiver/
Header:

api-key: kfggfgf.given_api_key_by_paylov

Request Parameters

Parameter	Type	Required	Description
cardNumber	string	Yes	Card number of the receiver. Accepts pan, token, or cardId

Note: Accepts pan, token, or cardId

• cardId: You can obtain cardId by adding a card to the Paylov system using the methods createUserCard followed by confirmUserCardCreate methods.
• token: You can retrieve the token by calling the endpoint p2p/receiver/list/.

Request example

{
  "cardNumber": "9860000000000000" # pan | cardId | token
}

Response example (SUCCESS)

{
  "result": {
    "card": {
      "holderName": "Test Test",
      "cardNumber": "986034******8888"
      "vendor": "Humo",
      "processing": "Humo"
    },
    "bank": {
      "id": 32,
      "name": "TengeBank"
    }
  }
}

Response example (FAIL)**

{
  "error": {
    "code": "card_not_found",
    "message": "card_not_found"
  }
}

---

2. Get Receiver Cards by Phone Number

Description: Retrieves the receiver's card information by phone number.

Endpoint details

Method: POST
URL: BASE_URL/merchant/p2p/receiver/list/
Header:

api-key: kfggfgf.given_api_key_by_paylov

Request parameters

Parameter	Type	Required	Description
phoneNumber	string	Yes	Phone number of the receiver (+998***)

Request example

{
  "phoneNumber": "+999*********"
}

Response example (SUCCESS)

{
  "result": {
    "cards": [
      {
        "holderName": "BOTIROV TEMURBEK",
        "masked_pan": "986034******8888",
        "token": "f04df295-4b58-4299-9dd4-72cd11e15512",
        "processing": "Humo",
        "vendor": "Humo"
      },
      {
        "holderName": "BOTIROV TEMURBEK",
        "masked_pan": "860003******3515",
        "token": "2133b7b9-45d9-496e-99da-77c11a817d8b",
        "processing": "Uzcard",
        "vendor": "Uzcard"
      }
    ]
  }
}

Response example (FAIL)

{
  "error": {
    "code": "card_not_found",
    "message": "card_not_found"
  }
}

💡 Note: The token field can be used as cardNumber in the Create P2P Transaction method.

---

3. Create P2P Transaction

Description: Initiates a P2P transaction between the sender and the receiver. In this part, only receiver info needed

Endpoint details

Method: POST
URL: BASE_URL/merchant/p2p/transfer/create/
Header:

api-key: kfggfgf.given_api_key_by_paylov

Request Body

Fields	sample_data	type	required	Description
cardNumber	9860000000000001	string	Yes	The card number or token of the receiver
amount	10000	int	Yes	The amount to be transferred
cardId	9f877739-bc25-4f0f-a13f-ec485fd04250	string	No	cardId that is created in Paylov system (payer card).
serviceId	9f877739-bc25-4f0f-a13f-ec485fd04250	string	No	Identifier provided by the payment provider to specify which terminal should be used for the money transfer. If not provided, the default terminal will be used.
commission	100	int	No	If the commission is charged by your side, you must provide it here in tiyin (1/100 of sum). This field does not apply for Humo2Humo and Humo2Uzcard transactions — in that case, the commission defined on the terminal will be automatically calculated based on the transaction amount.

Request example

{
  "cardNumber": "9860340101278885", # pan or token
  "amount": 10000     # amount in tiyn (100 = 1 SUM)
}

Response example

{
  "result": {
    "transactionId": "dad9cb0e-957c-47ab-841d-b4943f583a7a",
    "receiver": {
      "holderName": "Test Test",
      "cardNumber": "986034******8885",
      "amount": 10000,       # amount that reciver gets
      "commission": 0
    },
    "sender": {
      "holderName": null,
      "cardNumber": null,
      "amount": 10100,         # amount that will be withdrawn
      "commission": 100
    }
  }
}

---

4. Confirm Transaction

Description: Confirms the P2P transaction and completes the transfer.

Endpoint details

Method: POST
URL: BASE_URL/merchant/p2p/transfer/confirm/
Header:

api-key: kfggfgf.given_api_key_by_paylov

Request body

Parameter	Type	Required	Description
transactionId	string	Yes	The unique identifier of the transaction to confirm
cardId	string	Yes	The unique identifier of the card that is created in the Paylov system.

Request example

{
  "transactionId": "dad9cb0e-957c-47ab-841d-b4943f583a7a",
  "cardId": "5b01aea9-5ad3-4c6a-a721-220c449c8d14"
}

Response example

{
  "result": {
    "transactionId": "dad9cb0e-957c-47ab-841d-b4943f583a7a",
    "status": "paid",
    "amount": 10000,
    "commission": 100,
    "currency": 860
    "paid_at": "2024-08-13 14:30:45",
  },
  "error": null
}

Error Codes

• receiver_card_not_found
• receiver_card_not_valid
• unsupported_transfer
• same_cards
• server_error
• error_at_pay

Error Structure

{
  "error": {
    "code": "string",
    "message": "string",
	  "data": {} // dict or string, Null 
  }
}

# 'data' field might not be in error response