> For the complete documentation index, see [llms.txt](https://coda-payments.gitbook.io/coda-public-technical-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://coda-payments.gitbook.io/coda-public-technical-documentation/codapay/hosted-component-integration/cards/patch-a-transaction.md).

# Patch a Transaction

Use this endpoint to add non-critical data to a transaction after it has been initiated, but before it reaches a final state. The first supported field is `email`, used to deliver a digital receipt when the payment succeeds.

This is useful when you cannot collect the email before initiating the transaction — for example, a guest checkout, a backend-initiated transaction, or a flow where the email is entered on a later screen.

The patch endpoint is available on both **Hosted Payment Page** and **Hosted Component** integrations. The request and response are identical across both; only the base URL differs.

### Endpoint <a href="#endpoint" id="endpoint"></a>

Method: `POST`

<table><thead><tr><th width="136.1796875">Environment</th><th width="709.95703125">Base URL</th></tr></thead><tbody><tr><td>Sandbox</td><td><code>https://sandbox.codapayments.com/airtime/api/restful/v2.0/Payment/component/patch.json</code></td></tr><tr><td>Production</td><td><code>https://airtime.codapayments.com/airtime/api/restful/v2.0/Payment/component/patch.json</code></td></tr></tbody></table>

> **Note:** This endpoint is available on v2.0 only.

### When a Patch Is Accepted <a href="#when-a-patch-is-accepted" id="when-a-patch-is-accepted"></a>

* Status Restriction: Only `Pending` transactions can be updated. Requests for successful or failed transactions will be rejected. Pending transactions include: Init / Checkout / WaitToConfirm
* Rate Limit: A transaction can only be patched once. Subsequent requests will fail.
* Time Window: Transactions older than 3 months cannot be updated.

### Request Body <a href="#request-body" id="request-body"></a>

Send the request body in JSON format.

<table><thead><tr><th width="319.3515625">Parameter</th><th width="98.90234375">Type</th><th width="108.94140625">Required</th><th width="223.88671875">Description</th></tr></thead><tbody><tr><td><code>patchRequest</code></td><td>Object</td><td>Yes</td><td>Must be a valid JSON object.</td></tr><tr><td><code>patchRequest.apiKey</code></td><td>String</td><td>Yes</td><td>Your Coda API key.</td></tr><tr><td><code>patchRequest.projectId</code></td><td>String</td><td>Yes</td><td>Your project ID.</td></tr><tr><td><code>patchRequest.txnId</code></td><td>Numeric</td><td>Yes</td><td>The transaction ID returned by <code>init.json</code>.</td></tr><tr><td><code>patchRequest.profile</code></td><td>Object</td><td>No</td><td>User profile information, using the same structure as <code>init.json</code>.</td></tr><tr><td><code>patchRequest.profile.entry</code></td><td>Array</td><td>No</td><td>List of key-value pairs. The only key processed today is <code>email</code>.</td></tr><tr><td><code>patchRequest.profile.entry[].key</code></td><td>String</td><td>No</td><td>The profile entry key (e.g. <code>email</code>).</td></tr><tr><td><code>patchRequest.profile.entry[].value</code></td><td>String</td><td>No</td><td>The profile entry value. For <code>email</code>, this is the address where the receipt is sent on success.</td></tr></tbody></table>

A request that contains no profile entries is accepted as a no-op and returns success.

**Example Request**

```json
{
  "patchRequest": {
    "apiKey": "live_****************************",
    "projectId": "21",
    "txnId": 7714940366302672840,
    "profile": {
      "entry": [
        {
          "key": "email",
          "value": "jane.doe@example.com"
        }
      ]
    }
  }
}
```

### Response <a href="#response" id="response"></a>

A successful patch returns `resultCode` `0`. The response echoes the `txnId`.

{% tabs %}
{% tab title="Success" %}

```json
{
  "patchResult": {
    "resultCode": 0,
    "resultDesc": "Success",
    "txnId": 7714940366302672840
  }
}
```

{% endtab %}

{% tab title="Final State Rejection" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>  "patchResult": {
    "resultCode": 231,
    "resultDesc": "Transaction already marked as completed, cannot be processed again. (error:231)",
    "txnId": 7714940366302672840
  }
}
</code></pre>

{% endtab %}

{% tab title="Invalid Email" %}

```json
{
  "patchResult": {
    "resultCode": 103,
    "resultDesc": "A parameter in the request message sent to Coda is incorrect. (error:103)",
    "txnId": 7714940366302672840
  }
}
```

{% endtab %}
{% endtabs %}

#### Response Parameters <a href="#response-parameters" id="response-parameters"></a>

| Parameter                | Type    | Description                                                                                                                               |
| ------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `patchResult`            | Object  | Container for the patch result.                                                                                                           |
| `patchResult.resultCode` | Numeric | `0` on success. Otherwise an error code (see below). Describes the outcome of the patch call only — not the transaction's payment status. |
| `patchResult.resultDesc` | String  | `"Success"` on success; an error description otherwise.                                                                                   |
| `patchResult.txnId`      | Numeric | Echoes the `txnId` from the request.                                                                                                      |

### Error Codes <a href="#notes" id="notes"></a>

| Result Code | Description           | Troubleshooting / Reason                          |
| ----------- | --------------------- | ------------------------------------------------- |
| 103         | Invalid Parameter     | Missing required fields, or invalid email format. |
| 204         | Authentication Failed | Invalid `apiKey` or `projectId`.                  |
| 208         | Invalid Status        | Transaction is not in a `Pending` state.          |
| 236         | Merchant Mismatch     | The transaction belongs to another merchant.      |
| 241         | Transaction Too Old   | The transaction is older than 3 months.           |
| 413         | Transaction Not Found | Invalid or unrecognised `txnId`.                  |
| 473         | Already Patched       | This transaction has already been updated once.   |

### Typical Flow <a href="#typical-flow" id="typical-flow"></a>

```
Create Payment
      │
      ▼
Transaction Status = Pending
      │
      ├── Patch Profile (Allowed, once only)
      │
      ▼
Continue Payment Processing
      │
      ▼
Success / Failed / Expired
      │
      ▼
Patch No Longer Allowed
```

### Notes <a href="#notes" id="notes"></a>

* **Receipt delivery is not enabled by default.** To activate automated receipt delivery for your titles, contact the payment enablement team at <codapay_integration@coda.co>.
* **Last value wins.** If `email` was already set at init or by a previous patch, the new value replaces it. Patching with the value the field already holds returns success and changes nothing.
* **No webhook is sent for a patch.** Existing transaction completion notifications continue to fire on `Success` / `Failed` as usual. If `email` is set and receipt delivery is enabled, the receipt is sent to the value that is current when the transaction succeeds.