e-Próspera
Reference

Pay a partner application with a voucher

View as Markdown
POST
/api/v1/partner/residency_applications/{id}/pay/voucher

Applies a voucher that must cover the full invoice. Returns the updated application with nextSteps.paymentRequired false. Voucher errors carry a machine-readable code: voucher_not_found, voucher_expired, voucher_already_redeemed, voucher_not_applicable, voucher_not_full_coverage, invoice_not_found. Requires Idempotency-Key.

Authorization

partnerKey
AuthorizationBearer <token>

Partner Key for one approved Partner Integration. Keys are lifecycle- and scope-checked, and cross-integration resources are hidden.

In: header

Path Parameters

id*string
Formatuuid

Header Parameters

Idempotency-Key*string

8-128 URL-safe characters. Retained for 24 hours per integration and route. An identical retry replays the stored response with Idempotency-Replayed: true; a different body under the same key returns 409.

Match^[A-Za-z0-9_.~-]+$
Length8 <= length <= 128

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/partner/residency_applications/497f6eca-6276-4993-bfeb-53cbbbba6f08/pay/voucher" \  -H "Idempotency-Key: stringst" \  -H "Content-Type: application/json" \  -d '{    "voucherCode": "string"  }'
{  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "version": 1,    "statusId": "Draft",    "applicationVersion": "string",    "submittedAt": "2019-08-24T14:15:22Z",    "createdAt": "2019-08-24T14:15:22Z",    "approvedAt": "2019-08-24T14:15:22Z",    "rejectedAt": "2019-08-24T14:15:22Z",    "residentPermitNumber": "string",    "referralCode": "string",    "applicationData": {      "residencyType": "limited_e_resident",      "aoc": {        "aocId": "string",        "signed": true,        "signedByName": "string",        "signedAt": "2019-08-24T14:15:22Z",        "agentAuthorized": true      },      "personalDetails": {        "givenName": "string",        "surname": "string",        "email": "user@example.com",        "dateOfBirth": "string",        "sex": "string",        "countryOfBirth": "st",        "citizenships": [          "st"        ],        "alternateNamesAttestation": true,        "alternateNames": "string",        "criminalBackgroundAttestation": true,        "proofOfAddressUploadId": "374d34cb-fcc3-469a-9edd-37075e3acebb",        "address": {          "line1": "string",          "line2": "string",          "city": "string",          "state": "string",          "postalCode": "string",          "country": "st"        },        "phoneNumber": "string"      },      "information": {        "residencyReason": "string",        "referralSource": "string"      }    },    "applicantPortalAccess": {      "email": "user@example.com",      "hasLoggedIn": true,      "lastLogin": "2019-08-24T14:15:22Z",      "claimLinkSent": true,      "claimLinkSentAt": "2019-08-24T14:15:22Z"    },    "nextSteps": {      "agreementUrl": "http://example.com",      "proofOfAddressRequired": true,      "paymentRequired": true,      "verificationRequired": true,      "verificationInstructions": "string",      "submitReady": true    }  }}

Create a partner hosted-checkout session POST

Creates a hosted checkout for the application invoice. Send exactly one of `paymentProvider` or `paymentMethod`. `redirectUrl` must use an approved redirect origin; Stripe returns the payer to `redirectUrl?success=true` on success and to `redirectUrl` on cancel. The response is `{ data: { url }, invoiceId }`. Payment is confirmed asynchronously: poll the application until `nextSteps.paymentRequired` is false. Requires `Idempotency-Key`.

Create a secure agreement and KYC embed session POST

Requires `partner:person.embed_session.create`. The application must be partner-owned, complete except for agreement/KYC, and paid. The one-time URL is bound to the parent-held PKCE verifier and may only be framed by the selected allow-listed origin. Issuance is not idempotent: retrying this operation creates a replacement link and revokes any previously active embed session for the application.