> For the complete documentation index, see [llms.txt](https://passimpay.gitbook.io/passimpay-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://passimpay.gitbook.io/passimpay-api/integration-examples/h2h-payment-integration.md).

# H2H payment integration

The H2H method lets you accept cryptocurrency in your own payment form. Your server requests an address, displays the payment details and credits verified deposits received through webhooks.

**Method:** `POST https://api.passimpay.io/v2/address`

**Rate Limit:** 10 requests per second.

References: [Get address](https://passimpay.gitbook.io/passimpay-api/get-address), [Webhook Deposit](https://passimpay.gitbook.io/passimpay-api/webhook).

## Workflow

| Step | Action                                                  | Save in your application                            |
| ---- | ------------------------------------------------------- | --------------------------------------------------- |
| 1    | Create a local order and select currency and network    | Customer, `orderId`, `paymentId`                    |
| 2    | Request a deposit address                               | Returned `address` and `destinationTag`, if present |
| 3    | Display payment details and the current minimum deposit | Address, network and required tag                   |
| 4    | Verify an incoming `deposit` webhook                    | Transaction identity and received amount            |
| 5    | Apply your confirmation policy and duplicate protection | One accounting entry per verified deposit           |

## Request Body

| Name         | Type    | Description                                                          |
| ------------ | ------- | -------------------------------------------------------------------- |
| `platformId` | integer | Platform ID; supplied by the shared client                           |
| `paymentId`  | integer | Currency and network ID from the catalog                             |
| `orderId`    | string  | Local order identifier; up to 64 characters from `A-Za-z0-9+/=-:.,_` |

Save the order before sending the request. This method has no `amount` field and does not create a fixed-amount invoice.

## Request example

Use the [shared client](https://passimpay.gitbook.io/passimpay-api/integration-examples/signature-and-api-client.md).

{% tabs %}
{% tab title="Go" %}

```go
fields1 := map[string]any{
    "paymentId": 10,
    "orderId": "h2h-1001",
}
result1, err := client.Post("/v2/address", fields1)
if err != nil { return err }
fmt.Printf("PassimPay request result=%v\n", result1["result"])
```

{% endtab %}

{% tab title="PHP" %}

```php
$fields1 = [
    "paymentId" => 10,
    "orderId" => "h2h-1001",
];
$result1 = $client->post("/v2/address", $fields1);
echo "PassimPay request result=", $result1["result"], PHP_EOL;
```

{% endtab %}

{% tab title="Java" %}

```java
ObjectNode fields1 = new ObjectMapper().createObjectNode();
fields1.put("paymentId", 10);
fields1.put("orderId", "h2h-1001");
JsonNode result1 = client.post("/v2/address", fields1);
System.out.println("PassimPay request result=" + result1.path("result").intValue());
```

{% endtab %}

{% tab title="Python" %}

```python
fields1 = {
  "paymentId": 10,
  "orderId": "h2h-1001"
}
result1 = client.post("/v2/address", fields1)
print("PassimPay request result=", result1["result"])
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const fields1 = {
  "paymentId": 10,
  "orderId": "h2h-1001"
};
const result1 = await client.post("/v2/address", fields1);
console.log("PassimPay request result=", result1.result);
```

{% endtab %}

{% tab title="C#" %}

```csharp
var fields1 = JsonNode.Parse("""
{
  "paymentId": 10,
  "orderId": "h2h-1001"
}
""")!.AsObject();
var result1 = await client.PostAsync("/v2/address", fields1);
Console.WriteLine("PassimPay request result=" + result1["result"]!.GetValue<int>());
```

{% endtab %}
{% endtabs %}

## Successful response (200)

| Name             | Type    | Description                   |
| ---------------- | ------- | ----------------------------- |
| `result`         | integer | `1` indicates success         |
| `address`        | string  | Deposit address               |
| `destinationTag` | integer | Additional tag, when returned |

Treat a returned tag of `0` as a value. Test whether the field is present, rather than whether its value is truthy. For XRP, TON and other networks requiring a tag or comment, show the required value with the address.

Example payment details for your payment form:

```json
{
  "orderId": "h2h-1001",
  "currency": "BTC",
  "network": "Bitcoin",
  "address": "REPLACE_WITH_API_RESPONSE",
  "minimumDeposit": "REPLACE_WITH_CURRENT_LIMIT"
}
```

Use the address from the API response and current catalog limits. The values above are placeholders.

## Process deposits

Webhook `amount` is expressed in the deposited cryptocurrency. This example credits `amountReceive`, after deductions; document that policy in your customer balance logic.

For BTC, LTC, DOGE, BCH and DASH, a transaction may produce notifications at 1 and 2 confirmations, or only at 2 if detected later. The accounting example waits for 2 confirmations for these networks. This is an application policy; agree the confirmation threshold for each network before enabling it.

Use the [webhook accounting example](https://passimpay.gitbook.io/passimpay-api/integration-examples/webhooks-and-payment-accounting.md) to handle repeated and out-of-order events.

## Error handling

| Case                                      | Action                                                                          |
| ----------------------------------------- | ------------------------------------------------------------------------------- |
| No webhook received                       | Check history, notification delivery and your endpoint response                 |
| Deposit below the minimum                 | Reconcile the transfer; a missing webhook does not prove no funds were sent     |
| Required tag omitted                      | Send the deposit for reconciliation; do not identify the payer by address alone |
| Payment arrives late                      | Match it against saved payment details and the local order policy               |
| Different transactions pay the same order | Account for each verified deposit separately                                    |
