> ## Documentation Index
> Fetch the complete documentation index at: https://conto.finance/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Delta End-to-End Test

> Verify the Conto and Delta approval flow from payment request through reconciliation

# Delta End-to-End Test

Use this test after Delta has been enabled for your organization. It verifies that Conto creates
the approval, delivers the signed request, records the decision, and exposes the resulting payment
state to both operators and integrations.

## Prerequisites

<Check>The dashboard shows the Delta section</Check>
<Check>Your verification webhook is available at a public HTTPS URL</Check>
<Check>Your verification service and Conto use the same HMAC secret</Check>
<Check>The test vendor is accepted by both Delta and your Conto counterparty controls</Check>
<Check>You have an agent SDK key with the payment scopes required for your wallet flow</Check>

## Add Invoice Context

Include a durable invoice ID and hash so both systems can reconcile the decision and detect a
duplicate invoice.

```json theme={null}
{
  "invoice": {
    "id": "ACME-1003",
    "hash": "acme-1003-sha256-example",
    "vendorId": "acme-supplies",
    "vendorAddress": "0x1111111111111111111111111111111111111111",
    "expectedAmount": "45",
    "currency": "pathUSD",
    "payload": {
      "invoiceNumber": "ACME-1003",
      "lineItems": [
        {
          "description": "Office supplies",
          "amount": "45"
        }
      ]
    }
  }
}
```

## Managed-Wallet Flow

### 1. Request The Payment

```bash theme={null}
curl -X POST https://conto.finance/api/sdk/payments/request \
  -H "Authorization: Bearer $CONTO_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 45,
    "recipientAddress": "0x1111111111111111111111111111111111111111",
    "recipientName": "Acme Supplies",
    "purpose": "Invoice ACME-1003",
    "category": "SUPPLIES",
    "walletId": "wallet_id",
    "idempotencyKey": "delta-acme-1003",
    "context": {
      "invoice": {
        "id": "ACME-1003",
        "hash": "acme-1003-sha256-example",
        "vendorId": "acme-supplies",
        "vendorAddress": "0x1111111111111111111111111111111111111111",
        "expectedAmount": "45",
        "currency": "pathUSD"
      }
    }
  }'
```

The response should include:

* `status: "REQUIRES_APPROVAL"`
* a stable `requestId` and `approvalRequestId`
* a reason explaining that external verification is required
* a status or approval link when one is available

### 2. Verify Delivery And Decision

Confirm that your service receives a signed `approval.requested` event containing the same approval
reference and invoice context. Submit the approve or reject callback using the contract documented
in [Notification Channels](/docs/integrations/notification-channels).

For Delta verification responses that include evidence, use the callback URL provided during
onboarding. Send the exact JSON bytes that you sign, with an ISO 8601 `X-Conto-Timestamp` and an
`X-Conto-Signature` containing the lowercase HMAC-SHA256 of
`${X-Conto-Timestamp}.${rawBody}`.

```json theme={null}
{
  "decision": "APPROVED",
  "comment": "Invoice and mandate verified",
  "verification": {
    "proofType": "delta_signed",
    "proofRef": "https://verifier.example/proofs/proof_123",
    "evidenceHash": "sha256-example"
  }
}
```

The receipt returns stable reconciliation fields without echoing the evidence payload:

```json theme={null}
{
  "recorded": true,
  "idempotent": false,
  "approvalRequestId": "approval_123",
  "paymentRequestId": "payment_123",
  "decision": "approved",
  "status": "approved",
  "statusLabel": "Approved",
  "statusUrl": "/api/approval-requests/approval_123",
  "paymentStatusUrl": "/api/sdk/payments/payment_123",
  "nextAction": null,
  "message": "Decision recorded."
}
```

Retrying the same signed decision returns `recorded: true` with `idempotent: true`. Submitting a
different decision for the same verifier returns `DECISION_CONFLICT`.

After the callback, fetch the approval or payment status and verify that:

* the original approval reference is unchanged
* the decision and timestamp are visible
* a rejection includes a stable reason and does not proceed
* an approval moves the payment to the next supported action

### 3. Execute An Approved Payment

```bash theme={null}
curl -X POST https://conto.finance/api/sdk/payments/{requestId}/execute \
  -H "Authorization: Bearer $CONTO_AGENT_KEY"
```

Use the returned Conto transaction reference, network, status, and receipt or explorer link to
reconcile completion.

## External-Wallet Flow

For an external wallet, first authorize the proposed payment:

```bash theme={null}
curl -X POST https://conto.finance/api/sdk/payments/approve \
  -H "Authorization: Bearer $CONTO_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 45,
    "chainId": "42431",
    "senderAddress": "0xabc123def456789abc123def456789abc123def4",
    "recipientAddress": "0x1111111111111111111111111111111111111111",
    "recipientName": "Acme Supplies",
    "purpose": "Invoice ACME-1003",
    "category": "SUPPLIES",
    "context": {
      "invoice": {
        "id": "ACME-1003",
        "hash": "acme-1003-sha256-example",
        "vendorId": "acme-supplies",
        "vendorAddress": "0x1111111111111111111111111111111111111111",
        "expectedAmount": "45",
        "currency": "pathUSD"
      }
    }
  }'
```

Wait for the external verification decision, send the transfer with your signer, and then confirm
the transaction in Conto:

```bash theme={null}
curl -X POST https://conto.finance/api/sdk/payments/{requestId}/confirm \
  -H "Authorization: Bearer $CONTO_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "txHash": "0x..."
  }'
```

## Duplicate-Invoice Check

After the first completed test, resubmit the same invoice ID or hash with a new idempotency key.
Verify that the payment does not proceed and that the response and Delta record explain the
duplicate decision with a stable reason.

## Reconcile In The Dashboard

Use these customer-visible references to match the full flow:

* **Alerts & Approvals**: payment amount, approval state, reason, and next action
* **Delta**: verification state, invoice reference, decision, and proof reference
* **Transactions**: Conto transaction ID, network status, and receipt or explorer link

## Troubleshooting

| Symptom                                           | What To Check                                                          |
| ------------------------------------------------- | ---------------------------------------------------------------------- |
| No verification event arrives                     | Webhook URL, signature setup, delivery history, and workflow scope     |
| Event arrives but the callback is rejected        | HMAC secret, approval reference, callback expiry, and HTTP method      |
| Payment is approved without external verification | Organization, agent, and payment conditions on the workflow            |
| Verification rejects immediately                  | Vendor controls, invoice fields, amount, currency, and duplicate state |
| Approved payment does not complete                | Wallet custody path, payment status, SDK scopes, and next action       |

## Related Docs

<CardGroup cols={2}>
  <Card title="Delta Verification Setup" icon="sliders" href="/docs/guides/delta-setup">
    Prepare the organization and webhook connection
  </Card>

  <Card title="Payments API" icon="wallet" href="/docs/sdk/payments">
    Review payment lifecycle requests and response fields
  </Card>

  <Card title="Notification Channels" icon="tower-broadcast" href="/docs/integrations/notification-channels">
    Verify signatures, delivery, and callbacks
  </Card>

  <Card title="External Approvals" icon="shield-check" href="/docs/guides/external-approvals">
    Understand expiration, decisions, and proof fields
  </Card>
</CardGroup>