Skip to content

Logo

Startbutton

Boundaries are for maps, not businesses

Supports in this guide: Payments, Payouts

Provider website: startbutton.africa

What you need to do for start processing transactions (brief summary)

  1. Get your credentials (from Startbutton)
  2. Connect in Dashboard
  3. Send an API request

Prerequisites: get from Startbutton

Contact your Startbutton account manager to get your account verified and receive the following credentials. One Provider account connection covers both Payments and Payouts.

  • Public Key -> Corefy field public_key.
  • Secret Key -> Corefy field secret_key.
  • Use Type Field For Balance Slicing (optional) -> Corefy field use_type_field_for_balance_slicing -> confirm with your account manager whether your account needs this enabled.
Payments processing (connect Provider account, create payment-invoice)

Connect Provider account in Corefy Dashboard

Step 1 - Open connection form

Open Startbutton in the provider directory and press Connect at Startbutton Provider Overview page in the New connection section.

Step 2 - Fill in fields and select settings

  • Public Key
  • Secret Key
  • Use Type Field For Balance Slicing (optional)
  • Test Mode -> (enable if you are using sandbox credentials)

Choose Currency / Features; check with your Corefy account manager which methods are enabled for your account.

Success

You have connected Startbutton Provider account!

First request to Corefy API (MIN)

What it does: creates a payment-invoice. Card, SnapScan QR, and Swiffy EFT redirect the customer to a Startbutton-hosted page. Mobile money (MTN, AirtelTigo, Vodafone Pay, M-Pesa, Airtel Money, Tigo, and other mobile networks) and bank transfer instead return payment instructions directly in the response - see the important note below.

Payment - MIN

POST /api/payment-invoices 

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "2b3c4d5e-6f7a-4b8c-8d91-2e3f4a5b6c7d",
      "service": "payment_card_zar_hpp",
      "currency": "ZAR",
      "amount": 10,
      "customer": {
        "email": "johnsmith@gmail.com"
      }
    }
  }
}

Important

customer.email is required for card/SnapScan QR/Swiffy EFT - the request is rejected upfront if it's missing.

Payment - MAX

POST /api/payment-invoices 

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "3c4d5e6f-7a8b-4c9d-8e02-3f4a5b6c7d8e",
      "service": "payment_card_zar_hpp",
      "currency": "ZAR",
      "amount": 10,
      "customer": {
        "reference_id": "cus_123",
        "email": "johnsmith@gmail.com"
      }
    }
  }
}

Extended request (MAX)

Why add extra fields (typical reasons): - Provide additional customer details for compliance/reconciliation - Positively influence conversion rate - Include optional fields required by your specific flow

No Constants or Options are configured for this connector.

Important

Mobile money (e.g. mtn_ghs_invoice) - creates the payment and sends a prompt to customer.phone (or fields.phone); the customer approves it on their phone, then a separate confirmation step with the one-time code (OTP) they receive finalizes the payment.

Bank transfer (e.g. bank_transfer_zar_invoice) - creates the payment and returns bank transfer details (an account number to pay into) directly in the response; customer.email (or fields.email) is still used if available, but no OTP confirmation is needed.

Refunds

This connector does not support refunds.

Payouts processing (connect Provider account, create payout-invoice)

Connect Provider account in Corefy Dashboard

Uses the same Provider account connection as Payments above - one connection covers both directions, nothing extra to fill in for payouts specifically.

First request to Corefy API (MIN)

What it does: creates a payout-invoice and sends funds to a bank account or mobile money wallet. Startbutton covers a wide range of named banks across South Africa, Nigeria, Ghana, and Kenya, plus mobile money networks across Kenya, Ghana, Tanzania, Ivory Coast, Burkina Faso, Mali, Benin, Senegal, Togo, and Cameroon - the exact set depends on what's enabled for your account.

Payout - MIN

POST /api/payout-invoices 

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "reference_id": "4d5e6f7a-8b9c-4d0e-8f13-4a5b6c7d8e9f",
      "service": "standard_bank_zar",
      "currency": "ZAR",
      "amount": 10,
      "fields": {
        "account_number": "1231234",
        "beneficiary_first_name": "John",
        "beneficiary_last_name": "Doe"
      }
    }
  }
}

This connector also supports mobile money services such as mtn_ghs (field account_number, the recipient's own mobile money number).

Important

fields.account_number is required for both bank transfer and mobile money payouts. For bank transfer, the beneficiary name is taken from fields.beneficiary_first_name+fields.beneficiary_last_name, falling back to customer.name, then the full_name Constant.

Payout - MAX

POST /api/payout-invoices 

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "reference_id": "5e6f7a8b-9c0d-4e1f-8a24-5b6c7d8e9f0a",
      "service": "standard_bank_zar",
      "currency": "ZAR",
      "amount": 10,
      "customer": {
        "reference_id": "cus_123",
        "name": "John Smith",
        "address": {
          "country": "ZA"
        }
      },
      "fields": {
        "account_number": "1231234",
        "beneficiary_first_name": "John",
        "beneficiary_last_name": "Doe"
      }
    }
  }
}

customer.address.country is converted automatically to the country name Startbutton expects, with the country Constant as a fallback.

Extended request (MAX)

Why add extra fields (typical reasons): - Provide additional customer details for compliance/reconciliation - Positively influence conversion rate - Include optional fields required by your specific flow

Constants (fallback fields)

  • country -> fallback for customer.address.country.
  • full_name -> fallback for the beneficiary's name, when neither fields.beneficiary_first_name/beneficiary_last_name nor customer.name are provided.

Additional info

  1. Callback routing is automatic - Corefy generates the callback/return URLs per transaction, nothing to configure in Startbutton's own back-office.
  2. Active reconciliation is available - Payments support an active status request, in addition to the asynchronous callback.
  3. No refunds - this connector does not support refunds through Corefy.

FAQ / Troubleshooting

  • Invalid credentials / auth error -> verify Public Key/Secret Key for the selected environment
  • Payment fails with a missing email error -> customer.email is required for card/SnapScan QR/Swiffy EFT payments
  • Mobile money payment stuck waiting for confirmation -> the customer needs to approve the prompt on their phone and the OTP they receive must be submitted via the confirmation step
  • Refund request fails -> refunds aren't supported by this connector
  • Currency or service is not supported -> confirm allowed methods/currencies in your Startbutton account and in Corefy

Question

Still looking for help connecting your Startbutton account? Please contact our support team!