Integrate VayaPin into your software
Adding VayaPin to your app means three pieces of code: you ask for a customer's address, VayaPin sends it to you later, and you show it to whoever needs it.
Your coding assistant can build the whole integration. Copy this, and change the last part to describe your own app:
Read https://docs.vayapin.com/ai-prompt.md and follow it.
Build me a Python app that integrates VayaPin, so staff can look up a
customer's shipping address from an order.
/ai-prompt.md is the full instruction set as plain text. It works in Claude Code, Cursor, GitHub Copilot and anything else that reads a web page. If yours cannot open a URL, open that file yourself, paste all of it, then add your "build me…" line.
The rest of this page is what to build, whether you write it yourself or review what an assistant wrote.
Before you write any code
Set up two things in the dashboard. Neither has an API, so this part is manual however you build the rest.
- An API token — Dashboard → VayaCore → API Keys. Press
Generate Keyand copy the value; it is shown once. Your account needs an active API subscription. - A webhook endpoint — Dashboard → VayaCore → Webhooks. Register your public HTTPS URL and copy the signing secret; it is also shown once.
POST /v1/requests fails with 422 endpoint_not_provisioned until an enabled endpoint exists.
For local work your endpoint still has to be reachable from the internet. A tunnel does that:
ngrok http 3000
Register the tunnel URL as your webhook endpoint while you develop.
The three pieces
1. Ask for the address. Call POST /v1/requests with the customer's name, email and country, keyed by your own order id as the idempotency_key. You get back a request_id. The address is not in that response. See Getting started.
2. Receive it. VayaPin posts to your webhook endpoint once the customer confirms, which can take minutes or days. Check the signature, store the address, answer 2xx. See Receiving webhooks.
3. Show it. Every record needs a waiting state from the moment you create the request, because the address arrives separately.
Every endpoint, field and response code is in the API reference.
Four things that fail quietly
Most of an integration tells you when it breaks. These four do not, so check them whether you wrote the code or an assistant did.
| Check | Why it matters |
|---|---|
| The signature is checked over the raw body, before anything parses it | Parsing and re-serializing changes the byte order, and the signature no longer matches |
request_id is stored as a string | It is a UUID. Compared as a number, every webhook fails to match an order and nothing reports it |
A repeat event_id is ignored, a new one replaces the address | Dedup on request_id instead, and a customer who corrects their address keeps the old one |
An unmatched webhook answers 2xx | A 4xx tells VayaPin your endpoint is broken, and it stops retrying for good |
Already on a store platform?
If you run a WooCommerce store, the plugin does all of this for you. No code.
Where to read more
- Getting started — authentication, the request flow, error shapes, usage limits
- Receiving webhooks — signature checking, retries, deduplication
- API reference — every endpoint, field and response code
If none of them answers your question, tell us. A gap here is a gap we want to close.