Outgoing transfers

Guide to testing and simulating outgoing transfers in the Bre-B sandbox environment

Pay a target discovered in sandbox

The deterministic 101 and 102 discovery scenarios produce single-use targets that you can send in an outgoing transfer. A document-shaped plain_key ending in 102 is also reserved for payment by key. See target discovery in sandbox.

Successful simulation

To simulate a successful outgoing transfer in the sandbox environment, simply send a request with a valid payload structure that passes all business validations. No special field values are required.

{
  "tenant_account_id": "your_tenant_account_id",
  "transfers": [
    {
      "external_id": "transfer_001",
      "payment_id": "123856456",
      "amount": {
        "amount": 50000,
        "currency": "COP"
      },
      "description": "Payment for services",
      "query": {
        "format": "plain_key",
        "value": "user@email.com"
      }
    }
  ]
}

If you retrieve the outgoing transfer using this endpoint, you will see the transfer completed successfully:

{
  "id": "bbot_5tgliBmzjZ6mpQPRbQjfKj",
  "resolution_request_id": "bbtgr_5tgliBmzjZ6mpQPRbQjfKj",
  "state": "successful",
  "state_reason": null,
  ...
}

Error simulation

You can simulate errors in the sandbox environment through special rules that apply to certain field values of the payload. The following are the rules to simulate errors for the creation of outgoing transfers:

Condition One	Condition Two	Expected Error in State Reason
transfers[x].description contains "tx_unknown"		unknown
transfers[x].description contains "tx_amount_exceeds_balance_limit"		amount_exceeds_balance_limit
transfers[x].description contains "tx_creditor_account_not_found"		creditor_account_not_found
transfers[x].description contains "tx_invalid_creditor_account"		invalid_creditor_account
transfers[x].description contains "tx_risk_control"		risk_control
transfers[x].description contains "tx_breb_timeout"		breb_timeout
transfers[x].query.format = "plain_key"	transfers[x].query.value = "sandbox@tx_provider_unavailable.err"	provider_unavailable
transfers[x].query.format = "plain_key"	transfers[x].query.value = "sandbox@key_unknown.err"	unknown
transfers[x].query.format = "plain_key"	transfers[x].query.value = "sandbox@key_not_found.err"	key_not_found
transfers[x].query.format = "plain_key"	transfers[x].query.value = "sandbox@key_suspended.err"	key_suspended
transfers[x].query.format = "plain_key"	transfers[x].query.value = "sandbox@key_provider_unavailable.err"	provider_unavailable
transfers[x].query.format = "plain_key" and transfers[x].expected_creditor is set	transfers[x].query.value = "sandbox@key_target_creditor_mismatch.err"	target_creditor_mismatch

Note: These errors are related to internal communication with the Bre-B system and are different from errors related to data validation. These errors are reflected in the state_reason of the outgoing transfer.

Examples

Simulating a Key Not Found Error

If you want to simulate an error when the Bre-B key does not exist for the creation of outgoing transfers, you can send something like:

{
  "tenant_account_id": "your_tenant_account_id",
  "transfers": [
    {
      "external_id": "transfer_001",
      "payment_id": "123856456",
      "query": {
        "format": "plain_key",
        "value": "sandbox@key_not_found.err"
      }
    }
  ]
}

The response will be successful. Then, if you retrieve the outgoing transaction using this endpoint, you will see the error reflected in the state of the outgoing transfer:

{
  "id": "bbot_5tgliBmzjZ6mpQPRbQjfKj",
  "resolution_request_id": "bbtgr_5tgliBmzjZ6mpQPRbQjfKj",
  "state": "failed",
  "state_reason": "key_not_found",
  ...
}

Simulating a creditor mismatch when resolving a target

Resolve target accepts the same expected_creditor as a transfer by key. In sandbox, a plain key that isn't a sandbox trigger resolves to the creditor you expect, and sandbox@key_target_creditor_mismatch.err resolves to someone else:

{
  "tenant_account_id": "your_tenant_account_id",
  "format": "plain_key",
  "value": "sandbox@key_target_creditor_mismatch.err",
  "expected_creditor": {
    "document_type": "CC",
    "document_number": "1234567"
  }
}

The call answers 400 and persists no target:

{
  "code": "400 Bad Request",
  "errors": [
    {
      "error_code": "target_creditor_mismatch",
      "message": "The resolved creditor doesn't match the expected creditor",
      "path": "",
      "url": ""
    }
  ],
  "id": "log_7MkWaFqvfosB8fzHhb1Eql",
  "message": "Malformed request"
}

The target_resolution.failed webhook for the request carries "state_reason": "target_creditor_mismatch" and your expected_creditor. Send a regular key with the same expected_creditor to get a resolved response whose target.creditor matches it.