# Simulate a card decline

Send a card sale the sandbox always refuses, and handle the refusal where it actually arrives: in the response body, not as a transport error.

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. Send the sale at the declining amount

API call

`POST /api/transactions`

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

The cents of the amount pick the outcome, and the rest of the amount is ignored, so this is the same sale request as any other with one number changed.

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
    },
    "invoiceData": {
      "amounts": { "base": 10.01, "total": 10.01 }
    }
  }'
```

.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
    },
    invoiceData = new
    {
        amounts = new { @base = 10.01m, total = 10.01m }
    }
});

var result = await response.Content.ReadFromJsonAsync<JsonElement>();
var resultCode = result.GetProperty("responseData").GetProperty("resultCode").GetString();
```

### 2. Read the outcome off the response

On your side

The sandbox answers with the result code "Decline" and the message "AUTH DECLINED" in the response body. The platform files that result under the "Declined" outcome. The response carries host error 200. The refusal arrives on a successful HTTP response, because the request itself worked: a refused card is a business outcome, not a transport failure. An integration that decides on the status code alone reads this as a completed payment, which is the mistake this scenario exists to find.

[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": "Decline",
  "responseData": {
    "resultCode": "Decline",
    "resultMessage": "AUTH DECLINED"
  }
}
```

## 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
# Simulate a card decline
#
# Send a card sale the sandbox always refuses, and handle the refusal where it actually arrives: in
# the response body, not as a transport error.
#
# 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: Send the sale at the declining amount
call POST "/api/transactions" '{
  "transactionType": "Sale",
  "cardData": {
    "cardNumber": "4111111111111111",
    "nameOnCard": "Jane Doe",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "cvv": 123
  },
  "invoiceData": {
    "amounts": { "base": 10.01, "total": 10.01 }
  }
}' > /dev/null

# Step 2: Read the outcome off the response
# The sandbox answers with the result code "Decline" and the message "AUTH DECLINED" in the response
# body. The platform files that result under the "Declined" outcome. The response carries host error
# 200. The refusal arrives on a successful HTTP response, because the request itself worked: a
# refused card is a business outcome, not a transport failure. An integration that decides on the
# status code alone reads this as a completed payment, which is the mistake this scenario exists to
# find.
```

### PowerShell

```powershell
# Simulate a card decline
#
# Send a card sale the sandbox always refuses, and handle the refusal where it actually arrives: in
# the response body, not as a transport error.
#
# 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: Send the sale at the declining amount
$body = @'
{
  "transactionType": "Sale",
  "cardData": {
    "cardNumber": "4111111111111111",
    "nameOnCard": "Jane Doe",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "cvv": 123
  },
  "invoiceData": {
    "amounts": { "base": 10.01, "total": 10.01 }
  }
}
'@
$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 "Decline" and the message "AUTH DECLINED" in the response
# body. The platform files that result under the "Declined" outcome. The response carries host error
# 200. The refusal arrives on a successful HTTP response, because the request itself worked: a
# refused card is a business outcome, not a transport failure. An integration that decides on the
# status code alone reads this as a completed payment, which is the mistake this scenario exists to
# find.
```

### TypeScript

```typescript
// Simulate a card decline
//
// Send a card sale the sandbox always refuses, and handle the refusal where it actually arrives: in
// the response body, not as a transport error.
//
// 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: Send the sale at the declining amount
await call('POST', '/api/transactions', {
  "transactionType": "Sale",
  "cardData": {
    "cardNumber": "4111111111111111",
    "nameOnCard": "Jane Doe",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "cvv": 123
  },
  "invoiceData": {
    "amounts": { "base": 10.01, "total": 10.01 }
  }
});

// Step 2: Read the outcome off the response
// The sandbox answers with the result code "Decline" and the message "AUTH DECLINED" in the
// response body. The platform files that result under the "Declined" outcome. The response carries
// host error 200. The refusal arrives on a successful HTTP response, because the request itself
// worked: a refused card is a business outcome, not a transport failure. An integration that
// decides on the status code alone reads this as a completed payment, which is the mistake this
// scenario exists to find.
```

### C#

```csharp
// Simulate a card decline
//
// Send a card sale the sandbox always refuses, and handle the refusal where it actually arrives: in
// the response body, not as a transport error.
//
// 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: Send the sale at the declining amount
await CallAsync("POST", "/api/transactions", """
    {
      "transactionType": "Sale",
      "cardData": {
        "cardNumber": "4111111111111111",
        "nameOnCard": "Jane Doe",
        "expirationMonth": 12,
        "expirationYear": 2030,
        "cvv": 123
      },
      "invoiceData": {
        "amounts": { "base": 10.01, "total": 10.01 }
      }
    }
    """);

// Step 2: Read the outcome off the response
// The sandbox answers with the result code "Decline" and the message "AUTH DECLINED" in the
// response body. The platform files that result under the "Declined" outcome. The response carries
// host error 200. The refusal arrives on a successful HTTP response, because the request itself
// worked: a refused card is a business outcome, not a transport failure. An integration that
// decides on the status code alone reads this as a completed payment, which is the mistake this
// scenario exists to find.
```

### Python

```bash
pip install requests
```

```python
# Simulate a card decline
#
# Send a card sale the sandbox always refuses, and handle the refusal where it actually arrives: in
# the response body, not as a transport error.
#
# 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: Send the sale at the declining amount
call("POST", "/api/transactions", {
  "transactionType": "Sale",
  "cardData": {
    "cardNumber": "4111111111111111",
    "nameOnCard": "Jane Doe",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "cvv": 123
  },
  "invoiceData": {
    "amounts": { "base": 10.01, "total": 10.01 }
  }
})

# Step 2: Read the outcome off the response
# The sandbox answers with the result code "Decline" and the message "AUTH DECLINED" in the response
# body. The platform files that result under the "Declined" outcome. The response carries host error
# 200. The refusal arrives on a successful HTTP response, because the request itself worked: a
# refused card is a business outcome, not a transport failure. An integration that decides on the
# status code alone reads this as a completed payment, which is the mistake this scenario exists to
# find.
```

- [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.