🪝Webhooks

If you want to receive instant payloads when a payment is made, you can set up webhooks.

To receive webhooks for a Product, send_webhook must be true and webhook_url must be a valid POST endpoint you control.

Pay.so can send a POST request to a URL you specify immediately upon a successful or failed payment.

The request will contain the Resolved Payment data in the body.

You can write code to handle these requests. Non-coders might want to check out our Zapier integration!

Payload ⚡

{
    "payload": {
        "is_test": false,
        "id": "49bb61e1-3254-4eda-bd82-7c4b1043be57",
        "product_id": "4836b53d-f2a2-4f91-8923-facf97a16651",
        "expected_payment_id": "bcb20c9f-62e6-44be-8253-92668e52b4a1",
        "product_secret": "7grsphdpL1N95aSbmkFnhCqD",
        "slug": "ac7ce",
        "dollar_amount": "1.0",
        "metadata": null,
        "user": {
            "email": "[e-mail]",
            "custom_fields": {
                "full_name": "Chris Butcher"
            }
        },
        "payment": {
            "expected_token": {
                "symbol": "BUSD",
                "address": "0xeD24FC36d5Ee211Ea25A80239Fb8C4Cfd80f12Ee",
                "name": "Binance USD",
                "decimal_count": 18,
                "blockchain": "binance-smart-chain",
                "network": "testnet"
            },
            "received_token": {
                "symbol": "BUSD",
                "address": "0xeD24FC36d5Ee211Ea25A80239Fb8C4Cfd80f12Ee",
                "name": "Binance USD",
                "decimal_count": 18,
                "blockchain": "binance-smart-chain",
                "network": "testnet"
            },
            "expected_token_amount": "1.0",
            "received_token_amount": "1.0",
            "amount_difference": "0.0",
            "receiving_address": "0x43EF183c84079313fcE6fC65d93e569A2bd4Aafd",
            "sender_address": "0x84a58511E6a9B6bf6B0218d64D25DD7A354e485C",
            "tx_id": "0x3775b645f54a0c9fc8536848d79eff36e35fd4159e4fa1992217d30fc3b38880",
            "tx_success": true,
            "tx_failure": false,
            "swapped": false,
            "created_at": "2022-02-22T20:40:12.076Z"
        }
    }
}

Sending a test webhook 🔧

It can be annoying to have to make test payments just to get a webhook to fire so you can test your integration.

You can trigger a test from within the Pay.so interface.

1. Click here.

2. Click on the three dots under the 'Actions' column next to the Product you want to test the webhook for.

3. Click 'Integrations'.

4. Ensure send_webhook is true and webhook_url is valid. If they are not, you can update those details on that page.

5. Once they are, the 'Test webhook' button will be available.

6. Clicking it will send an example payload like that below to your endpoint as a POST request.

Test Payload ☁️

Note! The product_id and product_secret fields will contain accurate values while all other values will contain mock data. You can use product_secret in your integration code to verify that the request definitely came from us. This secret value is not visible anywhere else in Pay.so.

{
    "payload": {
        "is_test": true,
        "id": "testtest-test-test-test-testtesttest",
        "product_id": "4836b53d-f2a2-4f91-8923-facf97a16651",
        "expected_payment_id": "testtest-test-test-test-testtesttest",
        "product_secret": "7grsphdpL1N95aSbmkFnhCqD",
        "slug": "ac7ce",
        "dollar_amount": "10.0",
        "metadata": "testtesttesttesttesttesttesttesttesttesttesttesttesttesttesttest",
        "user": {
            "email": "[e-mail]",
            "custom_fields": {
                "full_name": "Test Name",
                "referrer": "Test Referrer"
            }
        },
        "payment": {
            "expected_token": {
                "symbol": "BUSD",
                "address": "0xeD24FC36d5Ee211Ea25A80239Fb8C4Cfd80f12Ee",
                "name": "Binance USD",
                "decimal_count": 18,
                "blockchain": "binance-smart-chain",
                "network": "testnet"
            },
            "received_token": {
                "symbol": "BUSD",
                "address": "0xeD24FC36d5Ee211Ea25A80239Fb8C4Cfd80f12Ee",
                "name": "Binance USD",
                "decimal_count": 18,
                "blockchain": "binance-smart-chain",
                "network": "testnet"
            },
            "expected_token_amount": "10.0",
            "received_token_amount": "10.0",
            "amount_difference": "0.0",
            "receiving_address": "0xtesttesttesttesttesttesttesttesttesttest",
            "sender_address": "0xtesttesttesttesttesttesttesttesttesttest",
            "tx_id": "0xtesttesttesttesttesttesttesttesttesttesttesttesttesttesttesttest",
            "tx_success": true,
            "tx_failure": false,
            "swapped": false,
            "created_at": "2022-02-22T20:40:12.076Z"
        }
    }
}

Automatic retries ♻️

If your server responds with a 2xx response code, the webhook will have been considered successfully delivered and will not be automatically retried.

If any other response code is received, the webhook will be scheduled to resend in 60 minutes.

If that also fails, it will be automatically scheduled to resend in another 60 minutes.

Three retries are attempted before Pay.so stops retrying and sends you an email to notify you there is a problem with your endpoint.

The retry schedule can be viewed in the Pay.so dashboard:

1. Click on 'Payments' in the left navbar.

2. Click on your Product to reveal the Resolved Payments.

3. Click on the three dots along side a Resolved Payment.

4. Click 'Events'

5. Click 'Webhooks'.

Here you can inspect past and pending webhooks as well as have the option to manually trigger a webhook.