Handling ZAR Mandates pre-transaction

You can validate if a Mandate is already in place for a specific ZAR::Bank transaction using the validation endpoint (please refer to /transactions/validate in our API documentation for further details).

If the mandate doesn’t exist, we will trigger a new process on your behalf.

Validate API request example

{
  "transaction": {
    "input_currency": "USD",
    "sender": {
      "country": "US",
      "phone_number": "+12124567890",
      "email": "test@example.com",
      "first_name": "First",
      "last_name": "Last",
      "city": "City",
      "street": "Street",
      "postal_code": "12345",
      "birth_date": "1970-01-01",
      "documents": [],
      "ip": "127.0.0.1",
      "metadata": {
        "sendRef": "SENDER-1234"
      }
    },
    "recipients": [
      {
        "requested_amount": "7040",
        "requested_currency": "ZAR",
        "payout_method": {
          "type": "ZAR::Bank",
          "details": {
            "first_name": "First",
            "middle_name": "Middle",
            "last_name": "Last",
            "street": "14 Main Street",
            "postal_code": "3280",
            "city": "Cape Town",
            "email": "recipient@email.com",
            "bank_code": "632005",
            "bank_account": "12345678",
            "phone_number": "+27119785313",
            "transfer_reason": "personal_account",
            "narration": "Birthday Gift"
          }
        }
      }
    ],
    "metadata": {
      "sendRef": "LOCAL-ID-1234"
    },
    "external_id": "806ec63a-a5a7-43cc-9d75-1ee74fbcc026"
  }
}

Validate API response examples

Mandate already signed (HTTP 200)

{
  "object": {
    "input_amount": 0.42,
    "input_currency": "USD",
    "metadata": {
    },
    "state": "approved",
    "sender": {
      "id": "043844c0-614c-4eca-bc40-466b78e5b855",
      // (...)
    },
    "payin_methods": [],
    "paid_amount": 0.0,
    "due_amount": 0.42,
    "recipients": [
      {
        "editable": true,
        "metadata": {
        },
        "state": "initial",
        "transaction_state": "initial",
        "type": "person",
        "retriable": true,
        "payout_method": {
          "type": "ZAR::Bank",
          "details": {
            "first_name": "First",
            "last_name": "Last",
            "bank_code": "632005",
            "bank_account": "12345678",
            "phone_number": "+27119785313",
            "transfer_reason": "personal_account",
            "street": "14 Main Street",
            "postal_code": "3280",
            "city": "Cape Town",
            "email": "recipient@email.com",
            "bank_name": "ABSA",
            "app_name": "MTO",
            "app_id": "649d6f5a-421e-48f6-beea-896f180a3e2b",
            "international_phone_number": "+27119785313",
            "nationalized_phone_number": "119785313"
          },
          "metadata": {
          },
          "provider": "bitpesa_auto",
          // (...)
          }
        },
        "exchange_rate": 23.80952380952381,
        "fee_fractional": 0,
        "transaction_external_id": "806ec63a-a5a7-43cc-9d75-1ee74fbcc026",
        "requested_amount": 10.0,
        "requested_currency": "ZAR",
        "input_amount": 0.42,
        "input_currency": "USD",
        "output_amount": 10.0,
        "output_currency": "ZAR"
      }
    ],
    "updated_at": "2024-05-16T13:04:26.888Z",
    "traits": {
    },
    "external_id": "04f14901-0554-402e-96e6-2958ca624871"
  }
}

Mandate in progress (HTTP 422)

{
  "object": {
    "input_amount": 0.42,
    "input_currency": "USD",
    "metadata": {
    },
    "state": "approved",
    "sender": {
      "id": "043844c0-614c-4eca-bc40-466b78e5b855",
      // (...)
    },
    "payin_methods": [],
    "paid_amount": 0.0,
    "due_amount": 0.42,
    "recipients": [
      {
        "editable": true,
        "metadata": {
        },
        "state": "initial",
        "transaction_state": "initial",
        "type": "person",
        "retriable": true,
        "payout_method": {
          "type": "ZAR::Bank",
          "details": {
            "first_name": "First",
            "last_name": "Last",
            "bank_code": "632005",
            "bank_account": "12345678",
            "phone_number": "+27119785313",
            "transfer_reason": "personal_account",
            "street": "14 Main Street",
            "postal_code": "3280",
            "city": "Cape Town",
            "email": "recipient@email.com",
            "bank_name": "ABSA",
            "app_name": "MTO",
            "app_id": "649d6f5a-421e-48f6-beea-896f180a3e2b",
            "international_phone_number": "+27119785313",
            "nationalized_phone_number": "119785313"
          },
          "metadata": {
          },
          "provider": "bitpesa_auto",
          // (...)
          }
        },
        "exchange_rate": 23.80952380952381,
        "fee_fractional": 0,
        "transaction_external_id": "806ec63a-a5a7-43cc-9d75-1ee74fbcc026",
        "requested_amount": 10.0,
        "requested_currency": "ZAR",
        "input_amount": 0.42,
        "input_currency": "USD",
        "output_amount": 10.0,
        "output_currency": "ZAR"
      }
    ],
    "updated_at": "2024-05-16T13:04:26.888Z",
    "errors": {
      "base": [
        {
          "error": "Mandate is in progress"
        }
      ],
      "main_error": [
        {
          "error": "Transaction details are invalid: Mandate is in progress"
        }
      ]
    },
    "traits": {
    },
    "external_id": "04f14901-0554-402e-96e6-2958ca624871"
  }
}

Note: On production, the recipient of a ZAR transaction will receive an email with instructions and a link that they can open to fill and sign the mandate. Once they sign the mandate, you can proceed to create the transaction using the same details used in the validate api call.

On sandbox, no emails are sent. You can reach out to our support team to sign the mandate on your behalf thus enabling you to create a transaction with a valid signed mandate.

Mandate failed to initiate (HTTP 422)

{
  "object": {
    "input_amount": 0.42,
    "input_currency": "USD",
    "metadata": {
    },
    "state": "approved",
    "sender": {
      "id": "043844c0-614c-4eca-bc40-466b78e5b855",
      // (...)
    },
    "payin_methods": [],
    "paid_amount": 0.0,
    "due_amount": 0.42,
    "recipients": [
      {
        "editable": true,
        "metadata": {
        },
        "state": "initial",
        "transaction_state": "initial",
        "type": "person",
        "retriable": true,
        "payout_method": {
          "type": "ZAR::Bank",
          "details": {
            "first_name": "First",
            "last_name": "Last",
            "bank_code": "632005",
            "bank_account": "12345678",
            "phone_number": "+27119785313",
            "transfer_reason": "personal_account",
            "street": "14 Main Street",
            "postal_code": "3280",
            "city": "Cape Town",
            "email": "recipient@email.com",
            "bank_name": "ABSA",
            "app_name": "MTO",
            "app_id": "649d6f5a-421e-48f6-beea-896f180a3e2b",
            "international_phone_number": "+27119785313",
            "nationalized_phone_number": "119785313"
          },
          "metadata": {
          },
          "provider": "bitpesa_auto",
          // (...)
          }
        },
        "exchange_rate": 23.80952380952381,
        "fee_fractional": 0,
        "transaction_external_id": "806ec63a-a5a7-43cc-9d75-1ee74fbcc026",
        "requested_amount": 10.0,
        "requested_currency": "ZAR",
        "input_amount": 0.42,
        "input_currency": "USD",
        "output_amount": 10.0,
        "output_currency": "ZAR"
      }
    ],
    "updated_at": "2024-05-16T13:09:56.848Z",
    "errors": {
      "base": [
        {
          "error": "Mandate signing failed to initiate, please retry"
        }
      ],
      "main_error": [
        {
          "error": "Transaction details are invalid: Mandate signing failed to initiate, please retry"
        }
      ]
    },
    "traits": {
    },
    "external_id": "04f14901-0554-402e-96e6-2958ca624871"
  }
}

Warning: Getting a successful validate response before instructing a transaction might be a requirement depending on your configurations in AZA.


Improve this page