Mock Testing Guide

cURL

curl --request GET \
  --url https://api.sandbox.capa.fi/api/partner/v2/transactions/mock-testing-guide \
  --header 'partner-api-key: <api-key>'

import requests

url = "https://api.sandbox.capa.fi/api/partner/v2/transactions/mock-testing-guide"

headers = {"partner-api-key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'partner-api-key': '<api-key>'}};

fetch('https://api.sandbox.capa.fi/api/partner/v2/transactions/mock-testing-guide', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.capa.fi/api/partner/v2/transactions/mock-testing-guide",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "partner-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.capa.fi/api/partner/v2/transactions/mock-testing-guide"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("partner-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.capa.fi/api/partner/v2/transactions/mock-testing-guide")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["partner-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "environment": "sandbox",
    "onRampRules": [
      {
        "fiatAmount": 10.01,
        "expectedStatus": "COMPLETED",
        "description": "Transaction completes successfully"
      },
      {
        "fiatAmount": 10.02,
        "expectedStatus": "CANCELLED (NAME_VERIFICATION_FAILED)",
        "description": "Bank beneficiary is not a KYC'd user"
      },
      {
        "fiatAmount": 1000.01,
        "expectedStatus": "COMPLETED",
        "description": "OTC transaction completes successfully"
      },
      {
        "fiatAmount": 1000.02,
        "expectedStatus": "CANCELLED (NAME_VERIFICATION_FAILED)",
        "description": "OTC bank beneficiary is not a KYC'd user"
      }
    ],
    "offRampRules": [
      {
        "cryptoAmount": 10.01,
        "expectedStatus": "COMPLETED",
        "description": "Transaction completes successfully"
      },
      {
        "cryptoAmount": 10.02,
        "expectedStatus": "CANCELLED (NAME_VERIFICATION_FAILED)",
        "description": "Bank beneficiary is not a KYC'd user"
      },
      {
        "cryptoAmount": 10.03,
        "expectedStatus": "CRYPTO_NOT_RECEIVED",
        "description": "Failure due to missing crypto transfer"
      },
      {
        "cryptoAmount": 1000.01,
        "expectedStatus": "COMPLETED",
        "description": "OTC transaction completes successfully"
      },
      {
        "cryptoAmount": 1000.02,
        "expectedStatus": "CANCELLED (NAME_VERIFICATION_FAILED)",
        "description": "OTC bank beneficiary is not a KYC'd user"
      },
      {
        "cryptoAmount": 1000.03,
        "expectedStatus": "CRYPTO_NOT_RECEIVED",
        "description": "OTC failure due to missing crypto transfer"
      }
    ],
    "crossRampRules": [
      {
        "sourceAmount": 2000.01,
        "expectedStatus": "COMPLETED",
        "description": "Walks the full lifecycle: PENDING_FUNDS -> FUNDS_RECEIVED -> IN_PROGRESS -> AWAITING_FUND_TRANSFER -> COMPLETED"
      },
      {
        "sourceAmount": 2000.02,
        "expectedStatus": "CANCELLED (NAME_VERIFICATION_FAILED)",
        "description": "Bank beneficiary is not a KYC'd user"
      },
      {
        "sourceAmount": 2000.03,
        "expectedStatus": "AWAITING_FUND_TRANSFER",
        "description": "Halts at AWAITING_FUND_TRANSFER so the payout leg can be exercised"
      }
    ]
  }
}

GET

api

partner

transactions

mock-testing-guide

cURL

curl --request GET \
  --url https://api.sandbox.capa.fi/api/partner/v2/transactions/mock-testing-guide \
  --header 'partner-api-key: <api-key>'

import requests

url = "https://api.sandbox.capa.fi/api/partner/v2/transactions/mock-testing-guide"

headers = {"partner-api-key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'partner-api-key': '<api-key>'}};

fetch('https://api.sandbox.capa.fi/api/partner/v2/transactions/mock-testing-guide', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.capa.fi/api/partner/v2/transactions/mock-testing-guide",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "partner-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.capa.fi/api/partner/v2/transactions/mock-testing-guide"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("partner-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.capa.fi/api/partner/v2/transactions/mock-testing-guide")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["partner-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "environment": "sandbox",
    "onRampRules": [
      {
        "fiatAmount": 10.01,
        "expectedStatus": "COMPLETED",
        "description": "Transaction completes successfully"
      },
      {
        "fiatAmount": 10.02,
        "expectedStatus": "CANCELLED (NAME_VERIFICATION_FAILED)",
        "description": "Bank beneficiary is not a KYC'd user"
      },
      {
        "fiatAmount": 1000.01,
        "expectedStatus": "COMPLETED",
        "description": "OTC transaction completes successfully"
      },
      {
        "fiatAmount": 1000.02,
        "expectedStatus": "CANCELLED (NAME_VERIFICATION_FAILED)",
        "description": "OTC bank beneficiary is not a KYC'd user"
      }
    ],
    "offRampRules": [
      {
        "cryptoAmount": 10.01,
        "expectedStatus": "COMPLETED",
        "description": "Transaction completes successfully"
      },
      {
        "cryptoAmount": 10.02,
        "expectedStatus": "CANCELLED (NAME_VERIFICATION_FAILED)",
        "description": "Bank beneficiary is not a KYC'd user"
      },
      {
        "cryptoAmount": 10.03,
        "expectedStatus": "CRYPTO_NOT_RECEIVED",
        "description": "Failure due to missing crypto transfer"
      },
      {
        "cryptoAmount": 1000.01,
        "expectedStatus": "COMPLETED",
        "description": "OTC transaction completes successfully"
      },
      {
        "cryptoAmount": 1000.02,
        "expectedStatus": "CANCELLED (NAME_VERIFICATION_FAILED)",
        "description": "OTC bank beneficiary is not a KYC'd user"
      },
      {
        "cryptoAmount": 1000.03,
        "expectedStatus": "CRYPTO_NOT_RECEIVED",
        "description": "OTC failure due to missing crypto transfer"
      }
    ],
    "crossRampRules": [
      {
        "sourceAmount": 2000.01,
        "expectedStatus": "COMPLETED",
        "description": "Walks the full lifecycle: PENDING_FUNDS -> FUNDS_RECEIVED -> IN_PROGRESS -> AWAITING_FUND_TRANSFER -> COMPLETED"
      },
      {
        "sourceAmount": 2000.02,
        "expectedStatus": "CANCELLED (NAME_VERIFICATION_FAILED)",
        "description": "Bank beneficiary is not a KYC'd user"
      },
      {
        "sourceAmount": 2000.03,
        "expectedStatus": "AWAITING_FUND_TRANSFER",
        "description": "Halts at AWAITING_FUND_TRANSFER so the payout leg can be exercised"
      }
    ]
  }
}

Returns the current mock testing configuration for the sandbox environment. Use specific transaction amounts to simulate different outcomes.

Mock testing is only available in the sandbox environment.

Mock Rules

On-Ramp Transactions

Use fiatAmount to trigger specific behaviors:

Fiat Amount	Expected Status	Description
`10.01`	`COMPLETED`	Transaction completes successfully
`10.02`	`CANCELLED` (NAME_VERIFICATION_FAILED)	Bank beneficiary is not the KYC’d user
`1000.01`	`COMPLETED`	OTC transaction completes successfully
`1000.02`	`CANCELLED` (NAME_VERIFICATION_FAILED)	OTC bank beneficiary is not the KYC’d user

Off-Ramp Transactions

Use cryptoAmount to trigger specific behaviors:

Crypto Amount	Expected Status	Description
`10.01`	`COMPLETED`	Transaction completes successfully
`10.02`	`CANCELLED` (NAME_VERIFICATION_FAILED)	Bank beneficiary is not a KYC’d user
`10.03`	`CRYPTO_NOT_RECEIVED`	Failure due to no crypto transfer
`1000.01`	`COMPLETED`	OTC transaction completes successfully
`1000.02`	`CANCELLED` (NAME_VERIFICATION_FAILED)	OTC bank beneficiary is not a KYC’d user
`1000.03`	`CRYPTO_NOT_RECEIVED`	OTC failure due to no crypto transfer

Cross-Ramp Transactions

Use sourceAmount to trigger specific behaviors:

Source Amount	Expected Status	Description
`2000.01`	`COMPLETED`	Walks the full lifecycle: `PENDING_FUNDS` → `FUNDS_RECEIVED` → `IN_PROGRESS` → `AWAITING_FUND_TRANSFER` → `COMPLETED`
`2000.02`	`CANCELLED` (NAME_VERIFICATION_FAILED)	Bank beneficiary is not a KYC’d user
`2000.03`	`AWAITING_FUND_TRANSFER`	Halts at `AWAITING_FUND_TRANSFER` so the payout leg can be exercised

For example, to create a cross-ramp that halts at AWAITING_FUND_TRANSFER:

{
  "userId": "12a121ad-cbea-4ec4-9e0a-5c861e528bba",
  "sourceAmount": 2000.03,
  "sourceCurrency": "MXN",
  "targetCurrency": "USD",
  "targetBankAccountId": "0b7e1c9f-3a4d-4f21-9a2e-5d8c6b1f4e30"
}

Cross-ramp uses its own 2000.0x band rather than reusing the on/off-ramp amounts. The internal on-ramp leg of a cross-ramp inherits the parent’s source amount, so a cross-ramp at 1000.01 would trigger the on-ramp rule underneath the cross-ramp one.

Cross-ramp specifics:

Only sourceAmount triggers a mock. On the targetAmount path the source amount is fee-derived and will never match a magic value.
If you create the transaction from a quoteId, the quote itself must have been created with sourceAmount set to one of the magic values.
The transaction advances through the real state machine, so every cross-ramp webhook fires in order — CREATED_CROSS_RAMP, FUNDS_RECEIVED_CROSS_RAMP, STARTED_PROCESSING_CROSS_RAMP, AWAITING_FUND_TRANSFER_CROSS_RAMP, and COMPLETED_CROSS_RAMP (or CANCELLED_CROSS_RAMP for 2000.02).

Important Notes

You must use the exact amounts specified above (10.01, 10.02, 10.03, 1000.01, 1000.02, 1000.03, 2000.01, 2000.02, 2000.03).
Transaction amount limits are not enforced for mock amounts. All other validation rules still apply (KYC status, etc.).
The system automatically handles state transitions to reach the target status.

Error Codes

Common Errors

HTTP Status	Code	Message
401	`UNAUTHORIZED`	”API Key is missing”
401	`UNAUTHORIZED`	”Invalid API Key format”
401	`UNAUTHORIZED`	”Invalid API Key”
403	`INVALID_PARTNER_FLOW`	”The partner has an invalid flow.”

Authorizations

partner-api-key

string

header

required

API key for the affiliated partner performing the request.

Response

This endpoint provides documentation for partners on how to trigger different transaction statuses using specific amounts.

Only available in testing environments.

success

boolean

Example:

true

data

object

Show child attributes

​Mock Rules

​On-Ramp Transactions

​Off-Ramp Transactions

​Cross-Ramp Transactions

​Important Notes

​Error Codes

​Common Errors

Authorizations

Response

Mock Rules

On-Ramp Transactions

Off-Ramp Transactions

Cross-Ramp Transactions

Important Notes

Error Codes

Common Errors