Pay IN H2F integration

In this document you may find the API methods for H2H integration of Pear2Pay.

(Authorization) Signatures

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

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.

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

Step 1: Generate Invoice

Endpoint:

POST https://pear2pay.io/api/v2/payments/merchant/generate_invoice/

Headers:

{
  "Content-Type": "application/json",
  "Authorization": "APIKey",
  "pear2pay-signature": "signature
}

Payload:

{
  "currency": "RUB",                    // Currency code (ISO 4217 format, e.g., RUB, USD, EUR)
  "order_id": "ORD-12345",              // Unique order ID from your system
  "amount": "1234.56",                  // Amount in fiat currency (string with dot as decimal separator)
  "callback_url": "https://your.site/callback",  // Your endpoint to receive status updates
  "success_url": "http://example.com/success",
  "fail_url": "http://example.com/fail",
  "client_id": "user-67890"            // Client identifier in your system
}

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

Step 2: Use Payment Form

A user-friendly and comprehensive form will open for you to fill in the required details.

Send the paymentURL to your clients so they can continue the payment process. This link opens a form that will guide your client step by step through the payment procedure, starting with the selection of a payment method and continuing with the entry of all necessary information. Each step is intuitive and straightforward, ensuring your client has a seamless experience as they proceed to the final stage of the transaction. Your clients can use this form to make changes and complete their payment easily.

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