Browse the docs

Create organization KYB link

POST /v2/api-gateway/organizations/{id}/kyb-link

Starts (or resumes) KYB for an organization you own and returns the verification URL. Returns 200, not 201. url is null when the organization is already in a status that cannot be restarted (APPROVED, IN_REVIEW, DECLINED); an unexpired URL is reused across calls, and a RETRY status issues a new one. Same semantics as POST /cardholders/{id}/kyc-link.

Request

Authentication: your API key in the x-api-key header.

Path parameters

Field	Type	Description
`id` required	string, uuid	Organization id (`id` from `GET /organizations`). Must be your organization or one of its children.

Headers

Field	Type	Description
`Idempotency-Key`	string	A unique string you choose, up to 255 characters, that makes this request safe to retry. If a request times out or fails in transit, send it again with the same key: the status code and body of the first attempt are returned and the operation is not performed a second time. Stored replies — including failures — are replayed for 24 hours, after which the same key starts a fresh request. Reusing a key for a different request, or sending it while the first request is still running, returns 409. Omit the header and the request behaves exactly as before. Document upload endpoints do not accept it.

Example request

cURL

curl --request POST \
     --url 'https://api.themooncard.com/v2/api-gateway/organizations/8d2cd518-5ef2-4280-91e8-63b1a0e672e7/kyb-link' \
     --header 'x-api-key: YOUR_API_KEY'

Responses

200 Success

Field	Type	Description
`url` required	string, nullable	Hosted verification URL the organization opens to complete verification. Null when the organization is already in a status that cannot be restarted (`APPROVED`, `IN_REVIEW`, `DECLINED`). An unexpired URL is reused across calls; a `RETRY` status issues a new one.
`status` required	string	Current KYB status: `NOT_STARTED`, `APPROVED`, `IN_REVIEW`, `DECLINED` or `RETRY`.

JSON

{
  "url": "https://verify.paywithmoon.com/kyb?token=eyJhbGciOiJIUzI1NiJ9.abc123",
  "status": "NOT_STARTED"
}

400 Error

Validation failed (errors[] lists each offending field) or a domain rule rejected the request ({ message, code }).