---
title: "Pay a partner application with a voucher"
method: POST
path: "/api/v1/partner/residency_applications/{id}/pay/voucher"
tags: ["Partner residency applications"]
---

# Pay a partner application with a voucher

`POST /api/v1/partner/residency_applications/{id}/pay/voucher`

## Request

- Base URL: `https://portal.eprospera.com`
- URL: `https://portal.eprospera.com/api/v1/partner/residency_applications/{id}/pay/voucher`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/eprospera/apis/e-pro-spera-api/docs/api/v1/partner/residency_applications/:id/pay/voucher/post.ts> (a function with typed inputs; its response is checked against the schema)

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`.

## Path parameters

- `id` string, uuid, required

## Headers

- `Idempotency-Key` string, required: 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.

## Request body

- PartnerVoucherRequest
  - `voucherCode` string, required

## Response `200`

Voucher applied; the application is returned.

- object: Successful response.
  - `data` PartnerResidencyApplication, required
    - `id` string, uuid, required
    - `version` integer, required
    - `statusId` 'Draft' | 'Pending Review' | 'Approved' | 'Rejected', required
    - `applicationVersion` string, required
    - `submittedAt` string, date-time, nullable, required
    - `createdAt` string, date-time, required
    - `approvedAt` string, date-time, nullable, required
    - `rejectedAt` string, date-time, nullable, required
    - `residentPermitNumber` string, nullable, required: 14-digit Resident Permit Number.
    - `referralCode` string, nullable, required
    - `applicationData` object, required
      - `residencyType` 'limited_e_resident' | 'e_resident' | 'resident_annual' | 'null', nullable, required
      - `aoc` object, required
        - `aocId` string, nullable, required
        - `signed` boolean, required
        - `signedByName` string, nullable, required
        - `signedAt` string, date-time, nullable, required
        - `agentAuthorized` boolean, required
      - `personalDetails` object, nullable, required
        - `givenName` string, required
        - `surname` string, required
        - `email` string, email, required
        - `dateOfBirth` string, required
        - `sex` string, required
        - `countryOfBirth` string, nullable, required
        - `citizenships` string[], required
        - `alternateNamesAttestation` boolean, required
        - `alternateNames` string, nullable, required
        - `criminalBackgroundAttestation` boolean, required
        - `proofOfAddressUploadId` string, uuid, nullable, required
        - `address` object, required
          - `line1` string, nullable, required
          - `line2` string, nullable, required
          - `city` string, nullable, required
          - `state` string, nullable, required
          - `postalCode` string, nullable, required
          - `country` string, nullable, required
        - `phoneNumber` string, nullable, required
      - `information` object, required
        - `residencyReason` string, nullable, required
        - `referralSource` string, nullable, required
    - `applicantPortalAccess` object, required
      - `email` string, email, nullable, required
      - `hasLoggedIn` boolean, required
      - `lastLogin` string, date-time, nullable, required
      - `claimLinkSent` boolean, required
      - `claimLinkSentAt` string, date-time, nullable, required
    - `nextSteps` object, required
      - `agreementUrl` string, uri, nullable, required
      - `proofOfAddressRequired` boolean, required
      - `paymentRequired` boolean, required
      - `verificationRequired` boolean, required
      - `verificationInstructions` string, nullable, required
      - `submitReady` boolean, required

## Other responses

- `400`: Invalid request body, application not in Draft, proof of address missing, missing `Idempotency-Key`, or a voucher error (`voucher_not_found`, `voucher_expired`, `voucher_not_applicable`, `voucher_not_full_coverage`).
- `401`: Missing or invalid credential.
- `403`: Partner Key lacks the required partner scope.
- `404`: Application not found or owned by another integration, or `invoice_not_found`.
- `409`: The applicant already has equivalent or higher residency rights, another application is in progress, or residency eligibility changed. Active residents may only upgrade; contact support for other changes. Renewals use billing, not a new application. Payment and voucher eligibility conflicts use code: residency_purchase_ineligible. `voucher_already_redeemed`, or `Idempotency-Key` reused with a different body.
- `429`: Partner API rate limit exceeded.
- `500`: Server error.

## Changes

- **2026-09-22** `d2c5a5cda002`: 7 info
  - added the optional property `code` to the response with the `400` status
  - added the optional property `code` to the response with the `401` status
  - added the optional property `code` to the response with the `403` status
  - added the optional property `code` to the response with the `404` status
  - …3 more
- **2026-09-15** `197106eab8bc`: 3 breaking, 3 warning, 14 info
  - the `header` request parameter `Idempotency-Key` became required
  - for the `header` request parameter `Idempotency-Key`, the minLength was increased from `1` to `8`
  - added the pattern `^[A-Za-z0-9_.~-]+$` to the `header` request parameter `Idempotency-Key`
  - for the `header` request parameter `Idempotency-Key`, the maxLength was set to `128`
  - …16 more

[Operation history](https://skmtc.dev/eprospera/apis/e-pro-spera-api/changes/api/v1/partner/residency_applications/:id/pay/voucher/post.md)

---

[API](https://skmtc.dev/eprospera/apis/e-pro-spera-api.md) - [All operations](https://skmtc.dev/eprospera/apis/e-pro-spera-api/llms.txt) - [OpenAPI document](https://skmtc.dev/eprospera/apis/e-pro-spera-api/revisions/271098460337?raw)