> For the complete documentation index, see [llms.txt](https://docs.coda.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coda.co/codapay/hosted-component-integration/alternative-payment-methods/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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.coda.co/codapay/hosted-component-integration/alternative-payment-methods/patch-a-transaction.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.