# Preparation for integration

### API Integration into Your Platform

1. [Login](https://account.passimpay.io/login) or [register](https://account.passimpay.io/register) a business account on our service.
2. Create a new platform in your dashboard.
3. Save the **Api Key** and **Platform ID** for future use.

### Payment Acceptance Options on Your Website

We offer two methods for integrating payments on your website:

### H2H (Host-to-Host) Method

The H2H option allows us to provide you with only the payment address, which you can insert into your own payment form. In this case, the user will not see which service is handling the payment processing. The design, flow, and method of displaying the payment window are entirely developed by you. This gives you the flexibility to create a unique payment experience that, based on your expertise, will yield the best conversion rates.

### Invoice Link Method

With the Invoice Link method, the user is redirected to our payment form, eliminating the need for you to develop the payment form from scratch. If customization is not a priority for you, the Invoice Link is the ideal solution.

**There are a few key points to note:**

* The **Invoice Link** is issued for a specific amount, and the payment status will only change to "Paid" after the full amount has been paid.
* With **H2H**, your user can pay any amount, and you will receive a callback with the actual payment amount.
* The **On-ramp** method is currently available only through the Invoice Link. Additionally, the Invoice Link provides the option to split payments. For instance, the user can pay part of the amount in USDT and the rest in BTC, as long as the final payment matches the invoice amount.

### H2H Method Workflow

1. **Address Request**: To initiate the payment process, request a payment address by calling the [endpoint](https://passimpay.gitbook.io/passimpay-api/get-address).
2. **Payment Confirmation**: After funds are credited to your wallet, you will receive a callback notification from our system at the [endpoint](https://passimpay.gitbook.io/passimpay-api/webhook).
3. **Callback Details**:
   * The payment amounts in the callback are always specified in the cryptocurrency used for the transaction.
   * The callback is triggered **ONLY** upon successful deposit. If you do not receive a callback, it means the user did not transfer funds to the specified address.
4. **Important Considerations**:
   * For payments made with **XRP**, **TON**, and other coins on similar networks, a **tag** will be provided along with the address. This tag must be displayed in your payment form.
   * If the user does not include the required tag, the system will be unable to identify the payer and associate the payment with your account.

### Invoice Link Method Workflow

1. **Create an Invoice**: To initiate a payment, create an invoice using the [endpoint](https://passimpay.gitbook.io/passimpay-api/create-an-invoice-link).
2. **Payment Confirmation**: After funds are credited to your wallet, you will receive a callback notification from our system at the [endpoint](https://passimpay.gitbook.io/passimpay-api/webhook).
3. **Check Invoice Status**: You can check the status of the invoice using the [endpoint](https://passimpay.gitbook.io/passimpay-api/check-invoice).
4. **Handling Partial Payments**:
   * If the invoice was **not fully paid**, you will receive a callback with the actual payment amount and a status of `waiting`. In this case, you have two options:
     * Inform the user that they need to pay the remaining amount to complete the invoice.
     * Credit the funds for the amount actually received.
5. **Invoice Expiry**: Invoice links are valid for selected time for payment. If the user does not pay within this time or makes a partial payment, the payment status will be set to `error` (for partial payments, the callback will include the actual amount received).

### Instant Payments Workflow

1. **Initiate a Withdrawal**: First, create a withdrawal order using the [endpoint](https://passimpay.gitbook.io/passimpay-api/withdraw).
2. **Check Payment Status**: After the withdrawal request is processed, you can check the status of the transaction through the [endpoint](https://passimpay.gitbook.io/passimpay-api/check-withdraw).
3. **Important Notes**:
   * The withdrawal request must be **in cryptocurrency**. For example, if you need to pay a user $100 in Litecoin (LTC), you must first convert this amount into LTC and submit the request for the equivalent amount (e.g., 1.3 LTC).
4. **Response Format**: Upon requesting withdraw, you will receive a response in the following format:

   ```json
   {
     "result": 1,
     "paymentId": 71,
     "addressTo": "TLBQDMM3zSLr2Tm88iujny5hBX5G7mS1Jd",
     "amount": "31.42",
     "transactionId": "Nzc2OTc0Njg2NDcyNjE3NzVmMzEzOTM4MzkzMjM2"
   }
   ```

   * The value `"Nzc2OTc0Njg2NDcyNjE3NzVmMzEzOTM4MzkzMjM2"` is our internal transaction hash, which can be used with the [`/withdrawstatus`](https://passimpay.gitbook.io/passimpay-api/check-withdraw) endpoint to retrieve detailed information about the payment.

#### IMPORTANT:

When depositing BTC, LTC, DASH, Dogecoin, or Bitcoin Cash, you will receive a callback **twice**:

1. After the **first confirmation**.
2. After the **second confirmation** of the transaction on the blockchain network.

#### Reasons why a callback was not received:

* You did not add our IP addresses to your whitelist.
* Your server is not responding correctly to our callback. In the transaction history in your Passimpay account, you can click on the transaction card to see the server response. You can also resend the callback from there.
* The user sent cryptocurrency but did not include the tag.
* The user sent an amount below the minimum deposit threshold in Passimpay. You can find the minimum deposit amounts [here](https://passimpay.gitbook.io/passimpay-api/list-of-cryptocurrencies).

#### Please note that all API requests must be signed, with the signature passed in the request headers.

Base URL: <https://api.passimpay.io>