POST legal_entity_applications/[id]/pay/voucher

Apply a voucher to the legal-entity application invoice. If the application is already signed, this also submits it for review.

Endpoint

POST /api/v1/legal_entity_applications/{id}/pay/voucher

Authentication

This endpoint accepts:

• a standard API key (sk-)
• an Agent Key (ak-) with the agent:entity.application.pay scope

Send the key in the Authorization header:

Authorization: Bearer <your-api-key-or-agent-key>

Preconditions

• The application must still be in Draft.
• The application must have been created through the public API.
• The voucher must fully cover the invoice amount.
• If you are using an Agent Key, the account owner must have created that key after signing a Manifestation of Will.

Signature is not required before calling this endpoint. If the application has not been signed yet, payment still succeeds and the response includes a reminder message.

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Legal-entity application ID.

Request Body

Field	Type	Required	Description
voucherCode	string	Yes*	Voucher code to apply to the application invoice.
couponCode	string	No	Deprecated alias for voucherCode, kept for backward compatibility. Prefer voucherCode; if both are sent, voucherCode wins.

* Provide either voucherCode or the deprecated couponCode.

Example Request

curl -X POST https://portal.eprospera.com/api/v1/legal_entity_applications/12345678-abcd-1234-abcd-123456789012/pay/voucher \
  -H "Authorization: Bearer <your-api-key-or-agent-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "voucherCode": "STARTUP100"
  }'

Response

Success Response (200 OK)

Field	Type	Description
success	boolean	Always true on success.
data	object	Application row after payment processing.
message	string	Present only when the invoice is paid but the application still needs a signature.

Example Response: paid, not yet signed

{
  "success": true,
  "data": {
    "id": "12345678-abcd-1234-abcd-123456789012",
    "statusId": "Draft",
    "applicationVersion": "1.0.0",
    "submittedAt": null,
    "createdAt": "2024-01-15T09:15:00.000Z",
    "approvedAt": null,
    "rejectedAt": null
  },
  "message": "Application paid, but not signed yet - please sign the application to complete the process."
}

Example Response: signed and submitted

{
  "success": true,
  "data": {
    "id": "12345678-abcd-1234-abcd-123456789012",
    "statusId": "Pending Review",
    "applicationVersion": "1.0.0",
    "submittedAt": "2024-01-15T11:30:00.000Z",
    "createdAt": "2024-01-15T09:15:00.000Z",
    "approvedAt": null,
    "rejectedAt": null
  }
}

Behavior

This endpoint:

1. verifies the application belongs to the API-key owner
2. verifies the application is still a draft
3. ensures an invoice exists
4. applies the voucher with full-coverage enforcement
5. submits the application immediately only if the Agreement of Coexistence is already signed

Status transitions

• If the application is unsigned: it stays Draft and returns a message.
• If the application is already signed: it moves from Draft to Pending Review.

Error Responses

400 Bad Request

Application is not a draft:

{
  "error": "Legal entity application is not in draft status"
}

Application was not created through the public API:

{
  "error": "This endpoint can only be used for API-created applications"
}

Invalid voucher:

{
  "error": "Voucher code is invalid"
}

Voucher expired:

{
  "error": "Voucher code has expired"
}

Voucher already redeemed:

{
  "error": "Voucher code has already been redeemed"
}

Voucher does not fully cover the invoice:

{
  "error": "Voucher code does not cover the full invoice amount"
}

404 Not Found

{
  "error": "Legal entity application invoice not found"
}

409 Conflict

Voucher payment succeeded, but automatic submission could not complete:

{
  "error": "Voucher payment was applied, but the application could not be submitted automatically. Open the application in the portal to review its current status."
}

401 Unauthorized

{
  "error": "Missing API key"
}

or:

{
  "error": "Invalid API key"
}

403 Forbidden

Agent Key missing the required scope:

{
  "error": "Insufficient permissions"
}

404 Not Found

{
  "error": "Legal entity application not found"
}

500 Internal Server Error

{
  "error": "Internal server error"
}

Notes

• Once the application reaches Pending Review, this endpoint can no longer be used.
• Successful Agent Key calls to this endpoint are audited and notify the account owner by email.