Skip to content

Integration

Visa Alias P2P transaction flow

  1. A customer indicates a recipient's phone number.
  2. A merchant submits the number to the PayCross system to get card details.
  3. The system sends the request to Visa Alias Service, gets card details and a card token linked to the phone number, and sends the token to the merchant.
  4. The merchant initiates a request to get the commission for transferring funds from the source card to the recipient card.
  5. The system notifies the merchant of a commission to be taken, if the P2P transaction is possible.
  6. The merchant informs the customer of the commission.
  7. The customer confirms the P2P transaction. The merchant initiate a P2P transaction request.
  8. The system processes the transaction and notifies the merchant of its status.

Requirements to requests

Each request to PayCross API must meet the following requirements:

  • use HTTP Basic authentication with Shop ID and Secret Key;
  • have the Content-Type: application/json, Accept: application/json, X-Api-Version: 3;
  • use the SSL connection with 128-bit (or stronger) encryption to meet PCI DSS requirements;
  • be UTF-8 encoded.

Get the recipient card details by a phone number

Request

Send a POST request to https://gateway.pay-cross.com/services/visa-alias/verify-phone with the following parameters:

Parameter Type Description
recipient_info object
phone_number * required
 string A recipient's phone number.
Request example 
{
    "recipient_info": {
      "phone_number": "375291234567"
    }
}
Response

If a phone number is used as an alias for the recipient card number, you get a response with the 200 status code.

Parameter Type Description
holder string The recipient cardholder name.
stamp string The recipient card stamp.
brand string The recipient card brand.
last_4 string The last 4 digits of the recipient card.
first_1 string The first digit of the recipient card.
bin string The recipient card BIN.
issuer_country string The country of the recipient card.
issuer_name string The issuing bank's name of the recipient card.
product * required
 string The recipient card product type.
exp_month integer The recipient card expiration month represented with 2 digits, for example 01.
exp_year integer The recipient card expiration year represented with 4 digits, for example 2021.
token string The recipient card token.
service_info object A section of the recipient's details.
recipientName string The recipient's name.
issuerName string The issuing bank of the recipient card.
cardType string The recipient card product type.
address1 string The recipient's address.
address2 string The recipient's additional address.
city string The recipient's city.
country string The recipient's country.
postalCode string The recipient's zip code.
Response example, if the phone number is used as an alias of the recipient card number 
{
    "holder": "Percy A G",
    "stamp": "3212dc99441c4997b2388abe5892f04c850df1dc67a17575203fff86ec1a7833",
    "brand": "visa",
    "last_4": "4895",
    "first_1": "4",
    "token": "a38bc9c6-b575-4a49-bc75-635c385398a9",
    "product": null,
    "bin": "470127",
    "issuer_country": null,
    "issuer_name": "Test Bank 1",
    "exp_month": 12,
    "exp_year": 2026,
    "service_info": {
        "recipientName": "Percy A G",
        "issuerName": "Test Bank 1",
        "cardType": "Visa Classic",
        "address1": "Street 1",
        "address2": "Region 1",
        "city": "Berlin",
        "country": "Germany",
        "postalCode": "00111"
    }
}

In case of a wrong phone number, you get a response with the 400 status code and an error description.

Response example in case of a wrong phone number 
{
  "error_code": "request_validation_error",
  "message": {
    "recipient_info": {
      "phone_number": [
        "is in invalid format"
      ]
    }
  },
  "status": "error",
  "code": "E.1025",
  "friendly_message": "Invalid request params"
}

If a phone number is not used as an alias of a card number in Visa Alias Service, you get a response with the 404 status code and an error description.

Response example if the phone number is not used as an alias of a card number 
{
  "status": "error",
  "code": "E.1037",
  "message": "Card Not Found",
  "friendly_message": "Card Not Found"
}

Get a commission for the P2P transaction

To get the commission for the P2P transaction, send a request to check the capability of the transaction. Set the recipient_card.token parameter to the received token value.

Execute a P2P transaction

If the P2P transaction is possible, send a P2P transfer request. Set the recipient_card.token parameter to the received token value.

If necessary, you can check a status of the P2P transaction. Send a status query request with the UID or tracking_id assigned to the transaction.