Pay IN H2H Integration

(Authorization) Signatures

To authenticate requests securely, Pear2Pay requires signatures included in the pear2pay-signature header. Here's how it works:

1. Generate API Key and Secret:
   • Create an API Key (Terminal) in the Merchant panel.
   • Copy both the API Key and Secret immediately, as they are displayed only once.

2. Signature Verification:
   • A signature is generated by hashing the request body using HMAC with your Secret Key.
   • The client sends the signature in the pear2pay-signature header, and the server verifies it by re-computing and comparing signatures.

How to get signature from secret key:

Signatures

Response:

[
    {
        "id": 20,
        "name": "СБП",
        "icon_url": "",
        "payment_types": [
            "PHONE_NUMBER"
        ],
        "purposes": [
            "SENDER",
            "RECIPIENT"
        ],
        "is_enabled": true,
        "required_fields": {
            "payout_fields": [
                {
                    "label": "Email of the payee",
                    "props": {
                        "type": "email",
                        "required": true
                    },
                    "field_name": "email",
                    "is_required": true
                },
                {
                    "label": "Receiver Name",
                    "props": {
                        "required": false
                    },
                    "field_name": "name",
                    "is_required": false
                },
                {
                    "label": "Payout Card Number",
                    "props": {
                        "required": true
                    },
                    "field_name": "payout_card_number",
                    "is_required": true
                }
            ],
            "invoice_fields": [
                {
                    "label": "Email of the payer",
                    "props": {
                        "type": "email",
                        "required": false # This prop only used for frontend form
                    },
                    "field_name": "email",
                    "is_required": false # If true, this field must be provided when creating an invoice.
                },
                {
                    "label": "Last 4 digits of phone number"
                    "props": {
                        "required": true
                    },
                    "field_name": "last_n_digits",
                    "is_required": true
                }
            ]
        }
    }
]

Response Body Description

Each object in the response represents a bank and contains the following fields:

• id: Unique identifier of the bank.

• name: Name of the bank.

• icon_url: URL of the bank's icon (can be used for displaying on the frontend).

• payment_types: List of supported payment types.

• purposes: List of purposes for which the bank can be used (e.g., SENDER, RECIPIENT).

• is_enabled: Indicates if the bank is currently enabled.

• required_fields: Contains information about additional fields required for payouts and invoices.
  • payout_fields: Fields required for payout operations (not used for invoice creation).
  • invoice_fields: Fields required for invoice creation. Each field includes:
    • label: Field label for display.
    • props: Additional properties (e.g., type, required).
    • field_name: Name of the field to be sent in the request.
    • is_required: If true, this field must be provided when creating an invoice. If false, the field is optional and should not be sent unless filled by the user.

Response:

{
  "invoice": {
    "id": 0,
    "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "amount": "-9405601953919476635261482964972025271708104021689402844024308216655547182274191821091115651592024269238789558142545989289",
    "status": "CREATED",
    "email": null,
    "client_id": "string",
    "geo": {
      "id": 0,
      "name": "string",
      "currency": "RUB"
    },
    "created_at": "2025-04-09T07:16:15.966Z",
    "order_id": "string",
    "cheque": "string",
    "crypto_amount": "string",
    "rate": "string",
    "fee": "64739.2",
    "success_url": "string",
    "fail_url": "string",
    "offer_card_holder_name": "string",
    "is_sum_changed": true,
    "payment_card": {
      "bank": {
        "id": 0,
        "name": "string",
        "icon_url": "string",
        "payment_types": [
          "CARD_NUMBER"
        ],
        "purposes": [
          "SENDER"
        ],
        "is_enabled": true,
        "required_fields": {
          "additionalProp1": "string",
          "additionalProp2": "string",
          "additionalProp3": "string"
        }
      },
      "number": "string",
      "currency": "RUB",
      "comment": "string",
      "full_holder_name": "string"
    }
  },
  "paymentURL": "string"
}

Invoice Creation Response

The response contains the following fields:

• id: Integer. Always present. The unique identifier of the invoice.

• uuid: String. Always present. The unique UUID of the invoice.

• amount: String. Always present. Represents the invoice amount as a string (internally a float or decimal).

• status: String. Always present. The current status of the invoice (one of the predefined statuses). Invoice Possible Statuses

• email: Nullable string. The payer's email, can be null.

• client_id: Nullable string. The client identifier, can be null.

• geo: Object. Contains information about the geography or region. The internal structure is not strictly required for integration.

• created_at: String (datetime). Always present. The creation date and time of the invoice.

• order_id: Nullable string. The order identifier, can be null.

• cheque: Nullable string. The cheque information, can be null.

• crypto_amount: String. Always present. The crypto amount as a string.

• rate: String. Always present. The exchange rate as a string.

• fee: String. Always present. The fee amount as a string.

• success_url: Nullable string. The URL to redirect to after successful payment. null

• fail_url: Nullable string. The URL to redirect to after failed payment. null

• offer_card_holder_name: Nullable string. The card holder's name for the offer, can be null.

• is_sum_changed: Boolean. Indicates if the sum was changed.

• payment_card: Nullable object. Contains payment details for the invoice. If present, has the following fields:
  • bank: Object. Information about the bank, including:
    • id: Integer. Bank identifier.
    • name: String. Bank name.
    • icon_url: String. URL for the bank icon.
    • payment_types: Array of strings. Supported payment types.
    • purposes: Array of strings. Supported purposes.
    • is_enabled: Boolean. Indicates if the bank is enabled.
    • required_fields: Object. Additional required fields for the bank.
  • number: String. The account or card number to which the payment should be sent.
  • currency: String. The currency code.
  • comment: Nullable string. Additional comment for the payment. null
  • full_holder_name: String. Full name of the card/account holder.

• paymentURL: String. The URL for making the payment. Do not use it in H2H integrations

Notes:

• All fields marked as "nullable" can be null.

• The geo object is included for reference but its internal structure is not required for most integrations.

• The payment_card object contains the payment details that should be shown to the user for completing the payment.

• In H2H integration you dont need paymentURL. Use it only if you are integrating H2F

Callback

When the status of an invoice is changed, a callback is sent to callback_url.

Endpoint:

POST callback_url

Headers:

{
  "Content-Type": "application/x-www-form-urlencoded",
  "pear2pay-signature": "signature"
}

Payload:

{
  "id": 2370,
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "amount": "1234.56",
  "status": "CONFIRMED",
  "email": "",
  "client_id": null,
  "geo": {
    "id": 4,
    "name": "RUB",
    "currency": "RUB"
  },
  "created_at": "2015-01-20T19:27:56.122994Z",
  "order_id": "string",
  "cheque": "Hidden",
  "crypto_amount": "123.45",
  "rate": "100",
  "fee": "0.0100",
  "success_url": "http://webhook.com/5717-4562-b3fc-2c963f66afa6/success",
  "fail_url": "http://webhook.com/5717-4562-b3fc-2c963f66afa6/fail",
  "offer_card_holder_name": null,
  "is_sum_changed": false,
  "payment_card": {
    "type": "bank",
    "number": "",
    "currency": "",
    "comment": "",
    "full_holder_name": ""
  },
  "signature": "signature"
}

Status Values:

Invoice Possible Statuses