### Install SDK Dependencies

Source: https://docs.stitch.money/payment-products/payins/wallets/once-off/web-integration-process-legacy

Commands to install the necessary SDK packages for different frameworks.

```bash
npm install @stitch-money/client @stitch-money/react
```

```bash
npm install @stitch-money/client @stitch-money/web
```

--------------------------------

### Install Stitch Money SDK for React

Source: https://docs.stitch.money/payment-products/payins/wallets/once-off/web-integration-process

Use this command to install the client and React-specific components.

```bash
npm install @stitch-money/client @stitch-money/react
```

--------------------------------

### Install Stitch SDK

Source: https://docs.stitch.money/payment-products/payins/card/secure-fields

Install the appropriate package based on your client-side framework.

```bash
npm install @stitch-money/react
```

```bash
npm install @stitch-money/web
```

--------------------------------

### Initialize ChargeIntent

Source: https://docs.stitch.money/payment-products/payins/inperson/driver/SDK/dotnet-framework

Examples for creating charge intents with or without cashback.

```csharp
var intent = new ChargeIntent(30.00m, "ZAR");  
```

```csharp
var intent = new ChargeIntent(  
    30.00m,  
    "ZAR",  
    new Money(5.00m, "ZAR"));  
```

--------------------------------

### Example Authorization URLs

Source: https://docs.stitch.money/authentication/user-tokens

Plausible examples of fully formed authorization URLs, provided in both URL-encoded and raw formats.

```text
https://secure.stitch.money/connect/authorize?client_id=test-18fbd892-3b73-43c3-a854-c6f78c681349 &  
scope=openid%20offline_access%20transactions%20accounts &  
response_type=code &  
redirect_uri=https%3A%2F%2Flocalhost%3A9000%2Freturn &  
state=J_Ug3dCQJG61Tt2Sejt3TY5ExgqemTXpEFhyFGapXwA &  
nonce=fim8Mwz0yHE85NOfgMD_sk3MdKzq2vQ_QnC0KUxIGT4 &  
code_challenge=FVF6VCwYJ_XljGdLXVjxs6g-_QRh4_CDutLOf_oIzPw &  
code_challenge_method=S256
```

```text
https://secure.stitch.money/connect/authorize?client_id=test-18fbd892-3b73-43c3-a854-c6f78c681349 &  
scope=openid offline_access transactions accounts &  
response_type=code &  
redirect_uri=https://localhost:9000/return &  
state=J_Ug3dCQJG61Tt2Sejt3TY5ExgqemTXpEFhyFGapXwA &  
nonce=fim8Mwz0yHE85NOfgMD_sk3MdKzq2vQ_QnC0KUxIGT4 &  
code_challenge=FVF6VCwYJ_XljGdLXVjxs6g-_QRh4_CDutLOf_oIzPw &  
code_challenge_method=S256
```

--------------------------------

### Initialize Charge Intents

Source: https://docs.stitch.money/payment-products/payins/inperson/driver/SDK/dotnet

Examples for creating charge intents with or without cashback.

```csharp
var intent = new ChargeIntent(Amount: 30.00m, Currency: "ZAR");  
```

```csharp
var intent = new ChargeIntent(  
    Amount: 30.00m,  
    Currency: "ZAR",  
    Cashback: new Money(5.00m, "ZAR"));  
```

--------------------------------

### Full Payment Request URL Example

Source: https://docs.stitch.money/payment-products/payins/bnpl/integration-process

Example of a complete URL with an appended redirect_uri query parameter.

```text
https://secure.stitch.money/connect/payment-request/2b068bd5-6a5a-42e1-8a45-673cb3ede612?redirect_uri=https%3A%2F%2Fexample.com%2Fpayment
```

--------------------------------

### Install Stitch Money SDK for Angular and JS

Source: https://docs.stitch.money/payment-products/payins/wallets/once-off/web-integration-process

Use this command to install the client and web-compatible components for non-React frameworks.

```bash
npm install @stitch-money/client @stitch-money/web
```

```bash
npm install @stitch-money/client @stitch-money/web
```

--------------------------------

### Initialize RefundIntent

Source: https://docs.stitch.money/payment-products/payins/inperson/driver/SDK/dotnet-framework

Example for creating a refund intent linked to an existing terminal session.

```csharp
var intent = new RefundIntent(  
    30.00m,  
    "ZAR",  
    "ts_abc123",  
    RefundReason.RequestedByUser);  
```

--------------------------------

### Initialize DisbursementIntent

Source: https://docs.stitch.money/payment-products/payins/inperson/driver/SDK/dotnet-framework

Example for creating a standalone disbursement intent.

```csharp
var intent = new DisbursementIntent(50.00m, "ZAR");  
```

--------------------------------

### REPLY file validation error example

Source: https://docs.stitch.money/payment-products/payins/debicheck/debit-order-files

Example of a REPLY file structure indicating validation failures for specific collection items.

```text
| Record type   | CLIENT_ID                            | PRODUCT                  | CHANNEL                       | FILE_TYPE          |  
|---------------|--------------------------------------|--------------------------|-------------------------------|--------------------|  
| P             | bf482d8d-0423-4a77-937b-a5b4d75bd734 | COLLECTIONS              | DEBIT ORDER                   | REPLY              |  
|---------------|--------------------------------------|--------------------------|-------------------------------|--------------------|-----------|-----------------------|----------------------------|-------------|  
| Record type   | LINE                                 | EXTERNAL_BATCH_REFERENCE | EXTERNAL_COLLECTION_REFERENCE | CONTRACT_REFERENCE | STATUS    | STATUS_CODE           | STATUS_REASON              | ACTION_DATE |  
|---------------|--------------------------------------|--------------------------|-------------------------------|--------------------|-----------|-----------------------|----------------------------|-------------|  
| D             | 6                                    | Batch_reference_1        | COLLECTION_REF_1              | CONTRACT_REF_1     | FAILED    | DATA_VALIDATION_ERROR | INVALID_BRANCH_CODE        |             |  
| D             | 7                                    | Batch_reference_1        | COLLECTION_REF_2              | CONTRACT_REF_2     | FAILED    | DATA_VALIDATION_ERROR | DUPLICATE_COLLECTION_NONCE |             |  
| D             | 8                                    | Batch_reference_1        | COLLECTION_REF_3              | CONTRACT_REF_3     | PROCESSED |                       |                            | 2026-07-14  |  
|---------------|--------------------------------------|--------------------------|-------------------------------|--------------------|-----------|-----------------------|----------------------------|-------------|  
| Record type   | TOTAL RECORDS                        |  
|---------------|--------------------------------------|  
| T             | 3                                    |
```

--------------------------------

### Example svix-signature Header Format

Source: https://docs.stitch.money/webhooks/using_webhooks

Shows the structure of the svix-signature header containing space-delimited signatures and version identifiers.

```text
v1,bm9ldHUjKzFob2VudXRob2VodWUzMjRvdWVvdW9ldQo= v2,MzJsNDk4MzI0K2VvdSMjMTEjQEBAQDEyMzMzMzEyMwo=
```

--------------------------------

### Sample REPLY File Structure

Source: https://docs.stitch.money/payment-products/payins/card/tokenization/collections/file-collections

An example of a REPLY file showing the status of processed and failed collection records.

```text
| RECORD_TYPE     | CLIENT_ID                              | PRODUCT                                                          | FILE_TYPE              |             |                          |                                  |  
|-----------------|----------------------------------------|------------------------------------------------------------------|------------------------|-------------|--------------------------|----------------------------------|  
| P               | bf482d8d-0423-4a77-937b-a5b4d75bd734   | REPLY                                                            | REPLY                  |             |                          |                                  |  
| --------------- | -------------------------------------- | ---------------------------------------------------------------- | ---------------------- | ----------- | ------------------------ | -------------------------------- |  
| RECORD_TYPE     | LINE                                   | TOKEN                                                            | AGREEMENT_REFERENCE    | STATUS      | STATUS_CODE              | STATUS_REASON                    |  
| --------------- | -------------------------------------- | ---------------------------------------------------------------- | ---------------------- | ----------- | -----------------------  | -------------------------------- |  
| D               | 6                                      | dG9rZW4vMTQ0NjZlYjAtMjlhMi00ZDM3LWIyYjctNTZkMWFkNWIxZWIw         | AGR_001                | FAILED      | DATA_VALIDATION_ERROR    | INVALID_QUANTITY                 |  
| D               | 7                                      | dG9rZW4vMTQ0NjZlYjAtMjlhMi00ZDM3LWIyYjctNTZkMWFkNWIxZWIy         | AGR_002                | FAILED      | DATA_VALIDATION_ERROR    | INVALID_NONCE                    |  
| D               | 8                                      | dG9rZW4vMTQ0NjZlYjAtMjlhMi00ZDM3LWIyYjctNTZkMWFkNWIxZWIz         | AGR_003                | SUCCESS     |                          |                                  |  
| --------------- | -------------------------------------- | ---------------------------------------------------------------- | ---------------------- | ----------- | ------------------------ | -------------------------------- |  
| RECORD_TYPE     | TOTAL_RECORDS                          |                                                                  |                        |             |                          |                                  |  
| --------------- | -------------------------------------- | ---------------------------------------------------------------- | ---------------------- | ----------- | ------------------------ | -------------------------------- |  
| T               | 3                                      |                                                                  |                        |             |                          |                                  |
```

--------------------------------

### Install Stitch.Terminal Package

Source: https://docs.stitch.money/payment-products/payins/inperson/driver/SDK/dotnet

Commands to add the Stitch.Terminal package to your .NET project.

```bash
dotnet add package Stitch.Terminal
```

```xml
<ItemGroup>  
  <PackageReference Include="Stitch.Terminal" Version="1.0.0" />  
</ItemGroup>
```

--------------------------------

### PaymentInitiationRequest Response Example

Source: https://docs.stitch.money/safe-link/frontend-integration

The JSON response received after creating a payment initiation request, containing the unique ID and secure URL.

```json
{
  "id": "cGF5cmVxL2JlMTNhMzE1LTBjZDUtNGY5Mi04NDk4LTU4YmU0M2Y3YjAyNg==",
  "url": "https://secure.stitch.money/connect/payment-request/be13a315-0cd5-4f92-8498-58be43f7b026"
}
```

--------------------------------

### Forward Pagination

Source: https://docs.stitch.money/graphql/pagination

Example of fetching a specific number of records using the 'first' argument and navigating using 'endCursor'.

```APIDOC
## GraphQL Query: Forward Pagination

### Description
Fetch a subset of records using forward pagination. Use the 'first' argument to define the page size and the 'after' argument with the 'endCursor' from the previous response to fetch subsequent pages.

### Parameters
- **first** (integer) - Required - Number of results to return per page.
- **after** (string) - Optional - Cursor to retrieve nodes after, typically the 'endCursor' of the previous page.

### Query Example
{
  client {
    paymentInitiationRequests(first: 10) {
      pageInfo {
        endCursor
        hasNextPage
      }
      edges {
        node {
          amount
          beneficiaryReference
          externalReference
          id
          created
          updated
        }
      }
    }
  }
}
```

--------------------------------

### Start a Terminal Session in .NET

Source: https://docs.stitch.money/payment-products/payins/inperson/driver/SDK/dotnet

Initiates a payment session by building a charge intent and request, then awaiting the terminal result.

```csharp
// Build the intent (what to charge)  
var intent = new ChargeIntent(  
    Amount: 25.00m,  
    Currency: "ZAR");  
  
// Build the request  
var request = new TerminalSessionCreateRequest  
{  
    Intent = intent,  
    ExternalReference = "order-456",  
    Customer = new Customer { Name = "Jane Doe", Email = "jane@example.com" },  
    Metadata = new Dictionary<string, string> { ["orderId"] = "12345" },  
};  
  
// Await the session result  
TerminalSession session = await terminal.StartSessionAsync(request);  
  
switch (session.Status)  
{  
    case SessionStatus.Success when session.Outcome is ChargeOutcome { Charge: var charge }:  
        Console.WriteLine($"Success! Charge ID: {charge.Id}");  
        break;  
    case SessionStatus.Failure:  
        Console.WriteLine($"Failed: {session.FailureReason}");  
        break;  
    case SessionStatus.Pending:  
        // Outcome is unknown  
        // Resolve via Terminal.GetSessionAsync(session.Id) or the Stitch HTTP API.  
        Console.WriteLine($"Pending: resolve session {session.Id}");  
        break;  
}  
```

--------------------------------

### Backward Pagination

Source: https://docs.stitch.money/graphql/pagination

Example of fetching records in reverse using the 'last' argument and navigating using 'startCursor'.

```APIDOC
## GraphQL Query: Backward Pagination

### Description
Fetch a subset of records using backward pagination. Use the 'last' argument to define the page size and the 'before' argument with the 'startCursor' from the previous response to fetch previous pages.

### Parameters
- **last** (integer) - Required - Number of results to return per page.
- **before** (string) - Optional - Cursor to retrieve nodes before, typically the 'startCursor' of the previous page.

### Query Example
{
  client {
    paymentInitiations(last: 100) {
      edges {
        node {
          amount
          date
          id
          beneficiaryReference
          payerReference
        }
      }
      pageInfo {
        startCursor
        hasPreviousPage
      }
    }
  }
}
```

--------------------------------

### Merchant Creation Response Examples

Source: https://docs.stitch.money/payment-products/payins/inperson/weave/merchants

Successful merchant creation responses for various business types and statuses.

```json
{
  "id": "bWVyY2hhbnQvNmM3OWVlZGEtY2E3Zi00ZDIwLThhNTgtN2JhYWI3MGY1ZTBk",
  "status": "pending",
  "externalReference": "demo-merchant-002",
  "businessType": "company",
  "mid": "991234567890123456",
  "name": "Stitch Demo Retail Ltd",
  "categoryCode": "7372",
  "phone": "+27123456789",
  "email": "demo@stitchdemo.co.za",
  "address": {
    "street": "123 Main Street",
    "city": "Cape Town",
    "postalCode": "8001",
    "regionCode": "WC",
    "countryCode": "ZA"
  },
  "bankAccount": {
    "number": "1234567890",
    "bank": "fnb",
    "accountHolderName": "Stitch Demo Retail Ltd"
  },
  "documents": [
    {
      "id": "ZmlsZS83ZDRiMGNmYi0xMDBhLTRkMjUtYWViYy0zN2YyOWEwZDA3NTM="
    }
  ],
  "pins": {
    "login": "111111",
    "supervisor": "123456"
  }
}
```

```json
{
  "id": "bWVyY2hhbnQvNmM3OWVlZGEtY2E3Zi00ZDIwLThhNTgtN2JhYWI3MGY1ZTBk",
  "status": "active",
  "externalReference": "demo-merchant-003",
  "businessType": "individual",
  "mid": "991112223334445556",
  "name": "Stitch Demo Retail Ltd",
  "categoryCode": "5945",
  "phone": "+27123456789",
  "email": "demo@stitchdemo.co.za",
  "address": {
    "street": "123 Main Street",
    "city": "Cape Town",
    "postalCode": "8001",
    "regionCode": "WC",
    "countryCode": "ZA"
  },
  "bankAccount": {
    "number": "1234567890",
    "bank": "fnb",
    "accountHolderName": "John Smith"
  },
  "documents": [
    {
      "id": "ZmlsZS83ZDRiMGNmYi0xMDBhLTRkMjUtYWViYy0zN2YyOWEwZDA3NTM="
    }
  ],
  "pins": {
    "login": "111111",
    "supervisor": "123456"
  }
}
```

```json
{
  "id": "bWVyY2hhbnQvNmM3OWVlZGEtY2E3Zi00ZDIwLThhNTgtN2JhYWI3MGY1ZTBk",
  "status": "pending",
  "externalReference": "demo-merchant-004",
  "businessType": "individual",
  "mid": "991998877665544332",
  "name": "Stitch Demo Retail Ltd",
  "categoryCode": "7995",
  "phone": "+27123456789",
  "email": "demo@stitchdemo.co.za",
  "address": {
    "street": "123 Main Street",
    "city": "Cape Town",
    "postalCode": "8001",
    "regionCode": "WC",
    "countryCode": "ZA"
  },
  "bankAccount": {
    "number": "1234567890",
    "bank": "fnb",
    "accountHolderName": "John Smith"
  },
  "documents": [
    {
      "id": "ZmlsZS83ZDRiMGNmYi0xMDBhLTRkMjUtYWViYy0zN2YyOWEwZDA3NTM="
    }
  ],
  "pins": {
    "login": "111111",
    "supervisor": "123456"
  }
}
```

--------------------------------

### Rendering the Payment Iframe

Source: https://docs.stitch.money/safe-link/frontend-integration

Examples for embedding the payment gateway using standard HTML or React components.

```html
<iframe
  name="paymentGatewayFrame"
  src="https://secure.stitch.money/connect/payment-request/0957174c-a600-4f7a-ac81-21a696338b0c?redirect_uri=https%3A%2F%2Fexample.com%2Fpayment"
  width="100"
  height="100"
>
</iframe>
```

```jsx
<iframe
  src={props.paymentRequestUrl + "?redirect_uri=" + props.redirectUri}
  width={100}
  height={100}
></iframe>
```

--------------------------------

### Example Payment Failed Error Response

Source: https://docs.stitch.money/payment-products/payins/linkpay/integration-process

A sample JSON response structure returned when a payment initiation fails.

```json
{
  "errors": [
    {
      "message": "Payment failed because insufficient funds were available.",
      "locations": [
        {
          "line": 4,
          "column": 23
        }
      ],
      "path": ["userInitiatePayment"],
      "extensions": {
        "code": "PAYMENT_FAILED",
        "reason": "insufficient_funds"
      }
    }
  ],
  "data": {
    "__typename": "Mutation",
    "userInitiatePayment": null
  }
}
```

--------------------------------

### Create and connect a terminal

Source: https://docs.stitch.money/payment-products/payins/inperson/driver/SDK/dotnet-framework

Initialize a terminal instance with a connection configuration and establish a connection.

```csharp
var config = ConnectionConfig.Serial(TerminalType.Android, "COM3");  
var terminal = new Terminal(config);  
  
TerminalStatus status = await terminal.ConnectAsync();
```

--------------------------------

### DebiCheck Webhook Payload Example

Source: https://docs.stitch.money/payment-products/payins/debicheck/integration-process

Example JSON payload received from a DebiCheck webhook notification.

```json
{
  "datetime": "2023-05-10T12:22:42.865Z",
  "id": "payment-consent-request:status:granted:cmVjdXJyaW5nUGF5bWVudENvbnNlbnRSZXF1ZXN0L2NiNmYyYmQ5LTVjODgtNDFmOS04MmE1LWE0NWEyNDYxMGJmNg==",
  "type": "payment-consent-request",
  "data": {
    "createdAt": "2023-06-11T11:52:49.230Z",
    "id": "cmVjdXJyaW5nUGF5bWVudENvbnNlbnRSZXF1ZXN0L2NiNmYyYmQ5LTVjODgtNDFmOS04MmE1LWE0NWEyNDYxMGJmNg==",
    "nonce": "2296ad8e-15a4-4f73-a0ad-fb9f7194fb52",
    "status": "GRANTED",
    "type": "DEBICHECK",
    "externalReference": "my-external-reference",
    "updatedAt": "2023-06-21T11:52:49.230Z",
    "metadata": {
      "billingAddress": "{\"addressLine1\": \"123 Test Street\",\"addressLine2\": \"Apartment 4A\",\"city\": \"Cape Town\", \"province\": \"Western Cape\",\"postalCode\": \"8001\",\"country\": \"ZA\"}"
    },
    "consentDetails": {
      "accountTracking": true,
      "contractReference": "CONTRACT123",
      "mandateReferenceNumber": "098765432123456789",
      "authenticationChannel": "authRealtime",
      "bankReasonCode": null,
      "bankReasonDescription": null,
      "collection": {
        "dayAdjustmentAllowed": true,
        "adjustmentAmount": 0,
        "adjustmentRate": 0,
        "amountAdjustmentFrequency": "annually",
        "collectionDay": 1,
        "debitValueType": "variable",
        "collectionFrequency": "monthly",
        "instalmentAmount": {
          "quantity": 1000,
          "currency": "ZAR"
        },
        "maximumCollectionAmount": {
          "quantity": 1500,
          "currency": "ZAR"
        },
        "firstCollectionDate": "2024-01-01",
        "firstCollectionAmount": {
          "quantity": 500,
          "currency": "ZAR"
        }
      },
      "customer": {
        "phoneNumber": "0821234567",
        "email": "john.doe@example.com",
        "accountName": "John Doe Account",
        "bankBranchCode": "123456",
        "accountNumber": "1234567890",
        "accountType": "CURRENT",
        "fullName": "John Doe",
        "identifyingDocument": {
          "type": "IDENTITY_DOCUMENT",
          "country": "ZA",
          "number": "8001015009087"
        }
      },
      "creditor": {
        "schemeName": "CREDITOR_SCHEME_001",
        "name": "Example Creditor Ltd",
        "phoneNumber": "+27123456789",
        "email": "creditor@example.com",
        "accountNumber": "9876543210",
        "branchCode": "654321",
        "ultimateCreditorName": "Ultimate Creditor Name",
        "ultimateCreditorAbbreviatedShortName": "UCN"
      }
    }
  }
}
```

--------------------------------

### Create PaymentsClient Instance

Source: https://docs.stitch.money/payment-products/payins/wallets/once-off/mobile-integration-process

Initializes the PaymentsClient using the configured environment.

```kotlin
fun createPaymentsClient(context: Context): PaymentsClient {  
    val walletOptions = Wallet.WalletOptions.Builder()  
        .setEnvironment(Constants.PAYMENTS_ENVIRONMENT)  
        .build()  
  
    return Wallet.getPaymentsClient(context, walletOptions)  
}
```

--------------------------------

### Create and connect a terminal

Source: https://docs.stitch.money/payment-products/payins/inperson/driver/SDK/java

Initialize a terminal instance using a connection configuration and establish the connection.

```java
ConnectionConfig config = ConnectionConfigBuilder.serial(TerminalType.ANDROID, "COM3").build();  
Terminal terminal = new Terminal(config);  
  
TerminalStatus status = terminal.connect();
```

--------------------------------

### Full Wallet Payment Integration Example

Source: https://docs.stitch.money/payment-products/payins/wallets/once-off/web-integration-process

A complete HTML structure demonstrating the integration of the pay-with-wallet custom element and the Stitch Wallet Client SDK.

```html
<!doctype html>  
<html lang="en">  
  <head>  
    <meta charset="UTF-8" />  
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />  
    <title>Stitch Wallet Payment Example</title>  
    <script  
      type="module"  
      src="https://cdn.stitch.money/@stitch-money/web@latest/pay-with-wallet/+esm"  
    ></script>  
  </head>  
  <body>  
    <stitch-pay-with-wallet  
      client-id="your-stitch-client-id"  
      stitch-gateway-merchant-id="your-gateway-merchant-id"  
      google-merchant-id="your-google-merchant-id"  
      merchant-name="Your Store Name"  
      total="100.00"  
      apple-pay-enabled  
      google-pay-enabled  
      samsung-pay-enabled  
    ></stitch-pay-with-wallet>  
  
    <script type="module">  
      import { StitchWalletClientSdk } from 'https://cdn.stitch.money/@stitch-money/client@latest/+esm';  
  
      const stitchClient = new StitchWalletClientSdk({  
        clientId: 'your-stitch-client-id',  
        gatewayMerchantId: 'your-gateway-merchant-id', // Required for Google Pay  
      });  
  
      const button = document.querySelector('stitch-pay-with-wallet');  
  
      // Define your verify and create callbacks (see Sample Implementation section below)  
      button.addEventListener('click', () => {  
        // Attach appropriate session handler based on wallet type  
        // See Sample Implementation section for complete examples  
      });  
    </script>  
  </body>  
</html>
```

--------------------------------

### Variable Consent Request Payload Example

Source: https://docs.stitch.money/payment-products/payins/capitec-pay-vrp/consents

Example JSON structure of a webhook payload received when a payment consent request status changes.

```json
{
  "clientId": "test-950f1098-dacf-4105-9958-c2319ab1a0bb",
  "data": {
    "createdAt": "2025-07-03T13:09:45.929+00:00",
    "id": "cGF5bWVudGNvbnNlbnRyZXF1ZXN0LzhmZjA2YWE0LWZkMzYtNDFlYi05NTlmLTQ0ZDQ0OTYyYzhlNA==",
    "status": "GRANTED",
    "type": "CAPITEC_PAY_RECURRING",
    "updatedAt": "2025-07-03T13:09:55.955+00:00"
  },
  "datetime": "2025-07-03T13:09:55.975Z",
  "id": "payment-consent-request:status:granted:8ff06aa4-fd36-41eb-959f-44d44962c8e4",
  "type": "payment-consent-request"
}
```

--------------------------------

### Constructed Redirect URL Example

Source: https://docs.stitch.money/payment-products/payins/debicheck/integration-process

An example of the full URL structure required to redirect a customer to the Stitch consent flow with an appended return URL.

```text
https://secure.stitch.money/v2/consent?requestId=2b068bd5-6a5a-42e1-8a45-673cb3ede612&  
    clientId=test-195944A9-E957-4532-B574-D37BD5FD9297&  
    returnUrl=https%3A%2F%2Fexample.com%2Fpayment  
```

--------------------------------

### Project Directory Structure

Source: https://docs.stitch.money/payment-products/payins/inperson/driver/SDK/dotnet-framework

Recommended file structure for storing the local NuGet package within your repository.

```text
your-solution/  
├── vendor/  
│   └── nuget/  
│       └── Stitch.Terminal.Native.1.0.0.nupkg  
├── src/  
│   └── YourApp/  
│       └── YourApp.csproj  
└── YourApp.sln  
```

--------------------------------

### GET /v2/tokens

Source: https://docs.stitch.money/payment-products/vault/tokens

Lists stored tokens with support for filtering and pagination.

```APIDOC
## GET /v2/tokens

### Description
Lists multiple stored tokens and filters the results using query parameters.

### Method
GET

### Endpoint
https://api.stitch.money/v2/tokens

### Parameters
#### Query Parameters
- **offset** (integer) - Optional - The number of records to skip before starting to return results.
- **limit** (integer) - Optional - The maximum number of records to return in the response.
- **externalReference** (string) - Optional - A unique identifier provided by the client to filter specific records.

### Response
#### Success Response (200)
- **data** (array) - An array of token objects.

### Response Example
{
  "data": [
    {
      "id": "dG9rZW4vMTQ0NjZlYjAtMjlhMi00ZDM3LWIyYjctNTZkMWFkNWIxZWIw",
      "card": {
          "bin": "42424242",
          "last4": "4242",
          "expiry": {
            "month": "02",
            "year": "29"
          },
          "network": "visa",
          "fundingType": "debit",
          "issuer": {
            "name": "fnb",
            "country": "za"
          }
      },
      "metadata": {
          "cardholderName": "Test User",
          "providers": [
            "name": "PSP",
            "token": "psp-token-123"
          ]
      },
      "externalReference": "user-123"
    }
  ]
}
```

--------------------------------

### Sale.startTransactionWithCashback

Source: https://docs.stitch.money/payment-products/payins/inperson/android-intent

Initiates a payment transaction including a cashback amount.

```APIDOC
## Sale.startTransactionWithCashback(amount, cashAmount, externalPosData)

### Description
Initiates a payment transaction with an additional cashback amount.

### Parameters
- **amount** (Long) - Required - The sale amount in cents.
- **cashAmount** (Long) - Required - The cashback amount in cents.
- **externalPosData** (Map<String, String>) - Optional - Key-value pairs for tracking identifiers or metadata.
```

--------------------------------

### GET /v2/merchants

Source: https://docs.stitch.money/payment-products/payins/inperson/weave/merchants

List multiple merchants with optional filtering and pagination.

```APIDOC
## GET /v2/merchants

### Description
List multiple merchants and filter the results using query parameters. Retrieval is paginated.

### Method
GET

### Endpoint
https://api.stitch.money/v2/merchants

### Parameters
#### Query Parameters
- **offset** (integer) - Optional - The number of records to skip before starting to return results.
- **limit** (integer) - Optional - The maximum number of records to return (max 100).
- **businessType** (string) - Optional - The merchant's business type.
- **externalReference** (string) - Optional - A unique identifier provided by the client to filter specific records.
- **mid** (string) - Optional - A unique MID assigned by Stitch.
- **status** (string) - Optional - The merchant's status on the Stitch platform.
```

--------------------------------

### GET /v2/merchants/{id}

Source: https://docs.stitch.money/payment-products/payins/inperson/weave/merchants

Retrieve a specific merchant by their unique identifier.

```APIDOC
## GET /v2/merchants/{id}

### Description
Retrieve a specific merchant by ID.

### Method
GET

### Endpoint
https://api.stitch.money/v2/merchants/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the merchant.
```

--------------------------------

### GET /terminals/{id}

Source: https://docs.stitch.money/payment-products/payins/inperson/weave/terminals

Retrieves a specific terminal by its unique identifier.

```APIDOC
## GET /terminals/{id}

### Description
Retrieves a specific terminal by its unique ID.

### Method
GET

### Endpoint
https://api.stitch.money/v2/terminals/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique terminal ID assigned by Stitch.
```

--------------------------------

### Retrieve Terminal and App Information

Source: https://docs.stitch.money/payment-products/payins/inperson/android-intent

Use the Info.Builder to initialize the request and define callbacks for success or error handling. The get() method triggers the intent execution.

```kotlin
override fun onCreate(savedInstanceState: Bundle?) {  
    ...  
    val info = Info.Builder(  
        this,  
        object : InfoListener {  
            override fun onInfoResult(result: InfoResult) {  
                // handle result  
            }  
  
            override fun onError(error: IntentError) {  
                // handle error  
            }  
        },  
    ).build()  
    ...  
}  
  
fun onButtonClick() {  
    info.get()  
}  
```

--------------------------------

### Initiate a Transaction

Source: https://docs.stitch.money/payment-products/payins/inperson/android-intent

Initialize the Sale builder in onCreate and trigger transactions using startTransaction or startTransactionWithCashback.

```kotlin
override fun onCreate(savedInstanceState: Bundle?) {  
    ...  
    val sale = Sale.Builder(  
        this,  
        object : SaleTransactionListener {  
            override fun onSaleResult(result: SaleResult) {  
                // handle response, setting a viewModel attribute  
            }  
  
            override fun alertError(error: IntentError) {  
                // handle error, setting a viewModel attribute  
            }  
        },  
    ).build()  
    ...  
}  
  
fun onButtonClick() {  
    val externalPosData = mapOf(  
        "posEg1" to UUID.randomUUID().toString(),  
        "posEg2" to Random().nextInt().toString(),  
        "posEg3" to true.toString(),  
    )  
    // the amount is represented in cents, so an amount of 1059 is R10.59  
    if (cashback) {  
        sale.startTransactionWithCashback(amount, cashAmount, externalPosData)  
    } else {  
        sale.startTransaction(amount, externalPosData)  
    }  
    ...  
}  
```

--------------------------------

### GET /v2/tokens/{id}

Source: https://docs.stitch.money/payment-products/vault/tokens

Retrieves a specific stored token by its unique ID.

```APIDOC
## GET /v2/tokens/{id}

### Description
Retrieves a specific stored token by ID.

### Method
GET

### Endpoint
https://api.stitch.money/v2/tokens/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the token.

### Response
#### Success Response (200)
- **id** (string) - The token ID.
- **card** (object) - Card details including bin, last4, expiry, network, fundingType, and issuer.
- **metadata** (object) - Metadata including cardholderName and providers.
- **externalReference** (string) - The external reference identifier.

### Response Example
{
  "id": "dG9rZW4vMTQ0NjZlYjAtMjlhMi00ZDM3LWIyYjctNTZkMWFkNWIxZWIw",
  "card": {
      "bin": "42424242",
      "last4": "4242",
      "expiry": {
        "month": "02",
        "year": "29"
      },
      "network": "visa",
      "fundingType": "debit",
      "issuer": {
        "name": "fnb",
        "country": "za"
      }
  },
  "metadata": {
      "cardholderName": "Test User",
      "providers": [
        "name": "PSP",
        "token": "psp-token-123"
      ]
  },
  "externalReference": "user-123"
}
```

--------------------------------

### Start a Terminal Session in Java

Source: https://docs.stitch.money/payment-products/payins/inperson/driver/SDK/java

Builds a charge intent and request, then initiates the session using the terminal SDK with a callback to handle success, failure, or error states.

```java
// Build the intent (what to charge)  
TerminalSessionIntent intent = TerminalSessionIntent.charge()  
    .amount(new BigDecimal("25.00"), "ZAR")  
    .build();  
  
// Build the request  
TerminalSessionCreateRequest request = TerminalSessionCreateRequest.builder()  
    .intent(intent)  
    .externalReference("order-456")  
    .customer(Customer.builder().name("Jane Doe").email("jane@example.com").build())  
    .metadata(Map.of("orderId", "12345"))  
    .build();  
  
// Callback receives the final session state  
TerminalSessionCallback callback = new TerminalSessionCallback() {  
    @Override  
    public void onSuccess(TerminalSession session) {  
        Charge charge = session.outcome().charge();  
        System.out.println("Success! Charge ID: " + charge.id());  
    }  
  
    @Override  
    public void onFailure(TerminalSession session) {  
        System.out.println("Failed: " + session.failureReason());  
    }  
  
    @Override  
    public void onError(TerminalSessionError error, TerminalSession session) {  
        // Outcome undetermined. Resolve via Stitch.getSession(session.id())  
        // or the Stitch HTTP API. Do not retry with the same intent.  
        System.out.println("Error: " + error.getMessage()  
            + ". Resolve session " + session.id());  
    }  
};  
  
// Start the session (returns immediately with PENDING snapshot)  
TerminalSession handle = terminal.createSession(request, callback);  
System.out.println("Session started: " + handle.id());
```

--------------------------------

### Terminal.StartSessionAsync

Source: https://docs.stitch.money/payment-products/payins/inperson/driver/SDK/dotnet

Initiates a payment session on the connected terminal.

```APIDOC
## Method: StartSessionAsync

### Description
Creates a session on a terminal to process a payment. The method returns a task that completes when the session reaches a terminal state.

### Signature
`Task<TerminalSession> StartSessionAsync(request, ...)`
```

--------------------------------

### GET https://api.stitch.money/v2/refunds/{id}

Source: https://docs.stitch.money/payment-products/payins/inperson/ota-api

Retrieves the status of a specific refund by its ID.

```APIDOC
## GET https://api.stitch.money/v2/refunds/{id}

### Description
Check the status of a specific refund at any time using its ID.

### Method
GET

### Endpoint
https://api.stitch.money/v2/refunds/{id}
```

--------------------------------

### GET /terminal-sessions/{id}

Source: https://docs.stitch.money/payment-products/payins/inperson/ota-api

Retrieves the status of a specific terminal session by its ID.

```APIDOC
## GET /terminal-sessions/{id}

### Description
Fetches the details and current status of a terminal session. This is useful for confirming payment results or if a webhook was missed.

### Method
GET

### Endpoint
/terminal-sessions/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the terminal session.
```

--------------------------------

### Create TerminalSessionCreateRequest

Source: https://docs.stitch.money/payment-products/payins/inperson/driver/SDK/dotnet

Initializes the request object required for starting a terminal session.

```csharp
var request = new TerminalSessionCreateRequest  
{  
    Intent = intent,  
    ExternalReference = "order-456",  
    Customer = new Customer { Name = "Jane Doe", Email = "jane@example.com" },  
    Metadata = new Dictionary<string, string> { ["orderId"] = "12345" },  
};  
```

--------------------------------

### UserInitiatePaymentInput GraphQL Schema

Source: https://docs.stitch.money/api/inputs/user-initiate-payment-input

Defines the input object structure for initiating payments.

```graphql
input UserInitiatePaymentInput {  
  amount: MoneyInput!  
  expireAt: Date  
  payerReference: String  
  beneficiaryReference: String  
  externalReference: String  
  merchant: String  
  payerInformation: PayerInformationInput  
}  
```

--------------------------------

### X-Stitch-Signature Header Format

Source: https://docs.stitch.money/webhooks_legacy

Example of the signature header containing a timestamp and the HMAC-SHA256 hash.

```text
X-Stitch-Signature: t=1670320325,hmac_sha256=b3c937fdf0adfa8bc51f18049100c4ea5b32c0305dafbc7429d1da633e6a9648
```

--------------------------------

### Disbursement Webhook Payload

Source: https://docs.stitch.money/payment-products/payouts/disbursements

Example JSON structure of a disbursement webhook event payload.

```json
{
  "data": {
    "client": {
      "disbursements": {
        "node": {
          "__typename": "Disbursement",
          "amount": {
            "currency": "ZAR",
            "quantity": "1"
          },
          "bankBeneficiary": {
            "__typename": "DisbursementBankBeneficiary",
            "accountHolder": "example-name",
            "accountNumber": "62741016950",
            "accountType": "savings",
            "bankId": "nedbank"
          },
          "beneficiaryReference": "example-ref",
          "created": "2022-10-06T15:03:08.436Z",
          "id": "ZGlzYnVyc2VtZW50Lzc2YTlhMjIwLWVjMGItNDJmOS04NGMzLTcyOGU4MjQ4MWVlNQ==",
          "linkedAccountId": null,
          "nonce": "bc70425a-9fa3-4db7-8e8b-93edb0b2aa23",
          "status": {
            "__typename": "DisbursementCompleted",
            "date": "2022-10-06T15:03:08.694Z",
            "expectedSettlement": "2022-10-08T15:03:08.694Z"
          }
        }
      }
    }
  }
}
```

--------------------------------

### terminal.connect()

Source: https://docs.stitch.money/payment-products/payins/inperson/driver/SDK/java

Establishes a connection to a payment terminal using a provided configuration.

```APIDOC
## terminal.connect()

### Description
Establishes a connection to a payment terminal using a previously configured `ConnectionConfig` object. This method returns the terminal's status once the connection is established.

### Usage
```java
ConnectionConfig config = ConnectionConfigBuilder.serial(TerminalType.ANDROID, "COM3").build();
Terminal terminal = new Terminal(config);
TerminalStatus status = terminal.connect();
```

### Exceptions
- `StitchTerminalException` with `ErrorCode.TERMINAL_UNAVAILABLE` if the terminal cannot be found (specifically when using `tcpBySerialNumber`).
```

--------------------------------

### Info.Builder

Source: https://docs.stitch.money/payment-products/payins/inperson/android-intent

Initializes the Info command builder with a listener to handle results or errors.

```APIDOC
## Info.Builder

### Description
Initializes the Info command to retrieve terminal and app information. The result is returned via the InfoListener.

### Method
Constructor

### Parameters
- **context** (Context) - Required - The Android context.
- **listener** (InfoListener) - Required - Callback interface with onInfoResult(InfoResult) and onError(IntentError) methods.

### Usage
```kotlin
val info = Info.Builder(this, object : InfoListener { 
    override fun onInfoResult(result: InfoResult) { /* handle result */ } 
    override fun onError(error: IntentError) { /* handle error */ } 
}).build()
```
```

--------------------------------

### Transaction Webhook Payload Example

Source: https://docs.stitch.money/payment-products/payins/card/once-off/secure-fields

Standard JSON structure for a transaction webhook event.

```json
{
  "data": {
    "amount": {
      "currency": "ZAR",
      "quantity": "1"
    },
    "card": {
      "bin": "41111111",
      "cardHolderName": "Joe Soap",
      "expiryMonth": 12,
      "expiryYear": 2024,
      "first6": "41111111",
      "id": "Y2FyZC85YWY4OGE4MS05ZjNhLTRlNDItYWRiYy04ZTA1M2Q1YTM3M2U=",
      "issuer": {
        "name": "capitec",
        "country": "ZA"
      },
      "last4": "1111",
      "maskedPan": "411111******1111",
      "network": "Visa",
      "type": "Credit"
    },
    "createdAt": "2023-05-10T12:22:42.865Z",
    "eci": "05",
    "externalReference": "79261d16-c53b-48eb-9019-dc9cfb6c5126",
    "id": "Y2FyZHRyYW5zYWN0aW9uLzQwNDMxRTY5LTNERjctNEIyQS1CNDY0LURFNTQwNDc0QkMxQw==",
    "nonce": "abb1c3b7-b39b-4a4c-93cb-3bbb363a3171",
    "originalAmount": {
      "currency": "ZAR",
      "quantity": "1"
    },
    "paymentRequestId": "RRFyZHRyYW5zYWN0aW9uLzQwNDMxRTY5LTNERjctNEIyQS1CNDY0LURFNTQwNDc0QkMxQw==",
    "primarySettlement": null,
    "retrievalReferenceNumber": "508714102541",
    "secure3dDecision": "skip",
    "secure3dDecisionReason": "clientSpecified",
    "splitSettlements": null,
    "status": "SUCCESS",
    "statusReason": null,
    "reasonDescription": null,
    "type": "CARD",
    "updatedAt": "2023-05-10T12:22:42.865Z"
  },
  "datetime": "2023-05-10T12:22:42.865Z",
  "id": "transaction:status:success:40431E69-3DF7-4B2A-B464-DE540474BC1C",
  "type": "transaction"
}
```

--------------------------------

### Reference Package in Project

Source: https://docs.stitch.money/payment-products/payins/inperson/driver/SDK/dotnet-framework

Methods for adding the SDK dependency to both modern SDK-style projects and legacy projects.

```xml
<ItemGroup>  
  <PackageReference Include="Stitch.Terminal.Native" Version="1.0.0" />  
</ItemGroup>  
```

```xml
<?xml version="1.0" encoding="utf-8"?>  
<packages>  
  <package id="Stitch.Terminal.Native" version="1.0.0" targetFramework="net472" />  
</packages>  
```

```powershell
Install-Package Stitch.Terminal.Native -Source StitchLocal  
```