# Trigger a partial approval

Send a card sale the sandbox approves for less than you asked for, so your integration has to read the authorized amount instead of assuming it.

2 steps, 1 API call

**Products:** Payments, Transactions

Samples use {{API_KEY}} for your API key and {{BASE_URL}} for this instance's API address. Anything else in double braces is a value an earlier step gave you.

## Reproduce it in the sandbox

### 1. Ask for a partial authorization

API call

`POST /api/transactions`

[Reference for this operation](https://devportal-simpay-sbx.winkpg.io/docs/api/transactionsCreate.md)

Partial approvals only happen when you say you accept them, so the request carries the control field below as well as the trigger amount. Control fields ride on a transaction custom field, and either spelling of the key works. If your sandbox merchant defines custom fields of its own, add this one as an enabled definition or use a merchant that defines none.

cURL:

```bash
curl -X POST "{{BASE_URL}}/api/transactions" \
  -H "api-key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionType": "Sale",
    "cardData": {
      "cardNumber": "4111111111111111",
      "nameOnCard": "Jane Doe",
      "expirationMonth": 12,
      "expirationYear": 2030,
      "cvv": 123
    },
    "customFields": [
      { "name": "loopback.partialAuthIndicator", "value": "true" }
    ],
    "invoiceData": {
      "amounts": { "base": 2.78, "total": 2.78 }
    }
  }'
```

.NET:

```csharp
using var http = new HttpClient { BaseAddress = new Uri("{{BASE_URL}}") };
http.DefaultRequestHeaders.Add("api-key", "{{API_KEY}}");

var response = await http.PostAsJsonAsync("/api/transactions", new
{
    transactionType = "Sale",
    cardData = new
    {
        cardNumber = "4111111111111111",
        nameOnCard = "Jane Doe",
        expirationMonth = 12,
        expirationYear = 2030,
        cvv = 123
    },
    customFields = new[]
    {
        new { name = "loopback.partialAuthIndicator", value = "true" }
    },
    invoiceData = new
    {
        amounts = new { @base = 2.78m, total = 2.78m }
    }
});

var result = await response.Content.ReadFromJsonAsync<JsonElement>();
var authorized = result.GetProperty("authorizedAmount").GetDecimal();
```

### 2. Read the outcome off the response

On your side

The sandbox answers with the result code "Partial" and the message "Partial Approval" in the response body. The platform files that result under the "PartialApproval" outcome. It authorizes 2.57 of the 2.78 you asked for, so the authorized amount on the response is the number to reconcile against. This is the case that overstates revenue without announcing it. The transaction approved, so the obvious checks pass, but only part of the amount is authorized. Collect the remainder another way, or release the balance.

[Testing your integration](https://devportal-simpay-sbx.winkpg.io/docs/testing.md)

**What this step answers with** (HTTP 200)

Abridged to the properties this step depends on. A real response carries more.

```json
{
  "id": "9f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "merchantId": "3a7b1c9d-2e4f-4a6b-8c8d-9e0f1a2b3c4d",
  "resultCode": "Partial",
  "authorizedAmount": 2.57,
  "responseData": {
    "resultCode": "Partial",
    "resultMessage": "Partial Approval",
    "isPartialApproval": true
  }
}
```

## Run the whole flow as one script

Every step above in one script you can copy and run. Replace {{API_KEY}} with your own API key and {{BASE_URL}} with this instance's API address, and set any value the script asks you for at the top. A step that happens outside the API stays a comment.

### cURL

```bash
brew install jq
```

```bash
#!/usr/bin/env bash
# Trigger a partial approval
#
# Send a card sale the sandbox approves for less than you asked for, so your integration has to read
# the authorized amount instead of assuming it.
#
# Every API call in this blueprint, in order. Each value a call returns is passed to the calls after
# it. A step that happens outside the API is a comment, and any failed call stops the script.

set -euo pipefail

BASE_URL="{{BASE_URL}}"
API_KEY="{{API_KEY}}"

# Sends one request and prints the response body. A failed call prints the API's answer and stops
# the script.
call() {
  local method="$1" path="$2" body="${3:-}" out
  local args=(-sS --fail-with-body -X "$method" "$BASE_URL$path" -H "api-key: $API_KEY")
  if [ -n "$body" ]; then
    args+=(-H "Content-Type: application/json" -d "$body")
  fi
  if ! out=$(curl "${args[@]}"); then
    printf '%s\n' "$out" >&2
    return 1
  fi
  printf '%s' "$out"
}

# Phase 1: Reproduce it in the sandbox

# Step 1: Ask for a partial authorization
call POST "/api/transactions" '{
  "transactionType": "Sale",
  "cardData": {
    "cardNumber": "4111111111111111",
    "nameOnCard": "Jane Doe",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "cvv": 123
  },
  "customFields": [
    { "name": "loopback.partialAuthIndicator", "value": "true" }
  ],
  "invoiceData": {
    "amounts": { "base": 2.78, "total": 2.78 }
  }
}' > /dev/null

# Step 2: Read the outcome off the response
# The sandbox answers with the result code "Partial" and the message "Partial Approval" in the
# response body. The platform files that result under the "PartialApproval" outcome. It authorizes
# 2.57 of the 2.78 you asked for, so the authorized amount on the response is the number to
# reconcile against. This is the case that overstates revenue without announcing it. The transaction
# approved, so the obvious checks pass, but only part of the amount is authorized. Collect the
# remainder another way, or release the balance.
```

### PowerShell

```powershell
# Trigger a partial approval
#
# Send a card sale the sandbox approves for less than you asked for, so your integration has to read
# the authorized amount instead of assuming it.
#
# Every API call in this blueprint, in order. Each value a call returns is passed to the calls after
# it. A step that happens outside the API is a comment, and any failed call stops the script.

$ErrorActionPreference = 'Stop'

$baseUrl = '{{BASE_URL}}'
$apiKey = '{{API_KEY}}'

# Sends one request and returns the parsed response body. A failed call stops the script.
function Invoke-BlueprintCall([string] $Method, [string] $Path, [string] $Body) {
    $arguments = @{
        Method  = $Method
        Uri     = $baseUrl + $Path
        Headers = @{ 'api-key' = $apiKey }
    }
    if ($Body) {
        $arguments.ContentType = 'application/json'
        $arguments.Body = [System.Text.Encoding]::UTF8.GetBytes($Body)
    }
    Invoke-RestMethod @arguments
}

# Phase 1: Reproduce it in the sandbox

# Step 1: Ask for a partial authorization
$body = @'
{
  "transactionType": "Sale",
  "cardData": {
    "cardNumber": "4111111111111111",
    "nameOnCard": "Jane Doe",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "cvv": 123
  },
  "customFields": [
    { "name": "loopback.partialAuthIndicator", "value": "true" }
  ],
  "invoiceData": {
    "amounts": { "base": 2.78, "total": 2.78 }
  }
}
'@
$null = Invoke-BlueprintCall -Method 'POST' -Path '/api/transactions' -Body $body

# Step 2: Read the outcome off the response
# The sandbox answers with the result code "Partial" and the message "Partial Approval" in the
# response body. The platform files that result under the "PartialApproval" outcome. It authorizes
# 2.57 of the 2.78 you asked for, so the authorized amount on the response is the number to
# reconcile against. This is the case that overstates revenue without announcing it. The transaction
# approved, so the obvious checks pass, but only part of the amount is authorized. Collect the
# remainder another way, or release the balance.
```

### TypeScript

```typescript
// Trigger a partial approval
//
// Send a card sale the sandbox approves for less than you asked for, so your integration has to
// read the authorized amount instead of assuming it.
//
// Every API call in this blueprint, in order. Each value a call returns is passed to the calls
// after it. A step that happens outside the API is a comment, and any failed call stops the script.

export {};

const baseUrl = '{{BASE_URL}}';
const apiKey = '{{API_KEY}}';

// Sends one request and returns the parsed response body. A failed call throws.
async function call(method: string, path: string, body?: unknown): Promise<any> {
  const headers: Record<string, string> = { 'api-key': apiKey };
  if (body !== undefined) {
    headers['Content-Type'] = 'application/json';
  }

  const response = await fetch(baseUrl + path, {
    method,
    headers,
    body: body === undefined ? undefined : JSON.stringify(body),
  });

  const text = await response.text();
  if (!response.ok) {
    throw new Error(`${method} ${path} answered ${response.status}: ${text}`);
  }

  return text ? JSON.parse(text) : null;
}

// Phase 1: Reproduce it in the sandbox

// Step 1: Ask for a partial authorization
await call('POST', '/api/transactions', {
  "transactionType": "Sale",
  "cardData": {
    "cardNumber": "4111111111111111",
    "nameOnCard": "Jane Doe",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "cvv": 123
  },
  "customFields": [
    { "name": "loopback.partialAuthIndicator", "value": "true" }
  ],
  "invoiceData": {
    "amounts": { "base": 2.78, "total": 2.78 }
  }
});

// Step 2: Read the outcome off the response
// The sandbox answers with the result code "Partial" and the message "Partial Approval" in the
// response body. The platform files that result under the "PartialApproval" outcome. It authorizes
// 2.57 of the 2.78 you asked for, so the authorized amount on the response is the number to
// reconcile against. This is the case that overstates revenue without announcing it. The
// transaction approved, so the obvious checks pass, but only part of the amount is authorized.
// Collect the remainder another way, or release the balance.
```

### C#

```csharp
// Trigger a partial approval
//
// Send a card sale the sandbox approves for less than you asked for, so your integration has to
// read the authorized amount instead of assuming it.
//
// Every API call in this blueprint, in order. Each value a call returns is passed to the calls
// after it. A step that happens outside the API is a comment, and any failed call stops the script.

using System.Text;
using System.Text.Json;

var baseUrl = "{{BASE_URL}}";
var apiKey = "{{API_KEY}}";

using var http = new HttpClient();
http.DefaultRequestHeaders.Add("api-key", apiKey);

// Sends one request and returns the parsed response body. A failed call throws.
async Task<JsonElement> CallAsync(string method, string path, string? body = null)
{
    using var request = new HttpRequestMessage(new HttpMethod(method), baseUrl + path);
    if (body is not null)
    {
        request.Content = new StringContent(body, Encoding.UTF8, "application/json");
    }

    using var response = await http.SendAsync(request);
    var json = await response.Content.ReadAsStringAsync();
    if (!response.IsSuccessStatusCode)
    {
        throw new HttpRequestException($"{method} {path} answered {(int)response.StatusCode}: {json}");
    }

    return json.Length == 0 ? default : JsonSerializer.Deserialize<JsonElement>(json);
}

// Phase 1: Reproduce it in the sandbox

// Step 1: Ask for a partial authorization
await CallAsync("POST", "/api/transactions", """
    {
      "transactionType": "Sale",
      "cardData": {
        "cardNumber": "4111111111111111",
        "nameOnCard": "Jane Doe",
        "expirationMonth": 12,
        "expirationYear": 2030,
        "cvv": 123
      },
      "customFields": [
        { "name": "loopback.partialAuthIndicator", "value": "true" }
      ],
      "invoiceData": {
        "amounts": { "base": 2.78, "total": 2.78 }
      }
    }
    """);

// Step 2: Read the outcome off the response
// The sandbox answers with the result code "Partial" and the message "Partial Approval" in the
// response body. The platform files that result under the "PartialApproval" outcome. It authorizes
// 2.57 of the 2.78 you asked for, so the authorized amount on the response is the number to
// reconcile against. This is the case that overstates revenue without announcing it. The
// transaction approved, so the obvious checks pass, but only part of the amount is authorized.
// Collect the remainder another way, or release the balance.
```

### Python

```bash
pip install requests
```

```python
# Trigger a partial approval
#
# Send a card sale the sandbox approves for less than you asked for, so your integration has to read
# the authorized amount instead of assuming it.
#
# Every API call in this blueprint, in order. Each value a call returns is passed to the calls after
# it. A step that happens outside the API is a comment, and any failed call stops the script.

import requests

BASE_URL = "{{BASE_URL}}"
API_KEY = "{{API_KEY}}"


# Sends one request and returns the parsed response body. A failed call raises.
def call(method, path, body=None):
    response = requests.request(
        method,
        BASE_URL + path,
        headers={"api-key": API_KEY},
        json=body,
    )
    response.raise_for_status()
    return response.json() if response.content else None


# Phase 1: Reproduce it in the sandbox

# Step 1: Ask for a partial authorization
call("POST", "/api/transactions", {
  "transactionType": "Sale",
  "cardData": {
    "cardNumber": "4111111111111111",
    "nameOnCard": "Jane Doe",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "cvv": 123
  },
  "customFields": [
    { "name": "loopback.partialAuthIndicator", "value": "true" }
  ],
  "invoiceData": {
    "amounts": { "base": 2.78, "total": 2.78 }
  }
})

# Step 2: Read the outcome off the response
# The sandbox answers with the result code "Partial" and the message "Partial Approval" in the
# response body. The platform files that result under the "PartialApproval" outcome. It authorizes
# 2.57 of the 2.78 you asked for, so the authorized amount on the response is the number to
# reconcile against. This is the case that overstates revenue without announcing it. The transaction
# approved, so the obvious checks pass, but only part of the amount is authorized. Collect the
# remainder another way, or release the balance.
```

- [Blueprints](https://devportal-simpay-sbx.winkpg.io/docs/blueprints.md): every blueprint this instance publishes.

## See also

- [All documentation](https://devportal-simpay-sbx.winkpg.io/llms.txt): the machine-readable index of every public page on this site.