Your first sandbox payment
Start with one sandbox agreement and one payment request. These examples use test credentials and the sandbox PayID sample@shabaas.com. Use Bash, curl and jq. Never paste credentials into tickets or commit them to GitHub.
1. Create your sandbox account and key
Create an account and open the sandbox workspace. In Settings → Developer Settings, generate an API key. Keep it server-side. If authentication reports that the merchant is inactive or developer credits are exhausted, resolve that account condition before continuing.
export SHABAAS_BASE_URL='https://dev-api.shabaas.com'
read -rs -p 'Sandbox API key: ' SHABAAS_API_KEY; echo
export SHABAAS_API_KEY
All commands below target the sandbox. Production access requires onboarding and approval. Never substitute production credentials while following this guide.
2. Exchange the key for a bearer token
curl --fail-with-body --silent --show-error \
-X POST "$SHABAAS_BASE_URL/api/public/authorization" \
-H "Authorization: $SHABAAS_API_KEY" > token.json
export SHABAAS_AUTHORIZATION="$(jq -er '.data.token' token.json)"
case "$SHABAAS_AUTHORIZATION" in
'Bearer '*) ;;
*) export SHABAAS_AUTHORIZATION="Bearer $SHABAAS_AUTHORIZATION" ;;
esac
rm token.json
Expected: HTTP 200 with data.token. The documented token already includes Bearer ; do not add it twice. Tokens are valid for 24 hours. A 401 means the key is invalid or the account is not active. See authentication.
3. Register your sandbox webhook receiver
Use an HTTPS receiver you control. It must accept POST JSON, verify the exact Authorization header value against the secret you configure, durably record the event and return a successful HTTP response. Handle duplicates and out-of-order events. Use status retrieval to reconcile outcomes; do not initiate another payment because an event is missing.
export SHABAAS_WEBHOOK_BASE='https://YOUR-SANDBOX-RECEIVER.example'
read -rs -p 'Webhook shared secret (8-200 characters): ' SHABAAS_WEBHOOK_SECRET; echo
export SHABAAS_WEBHOOK_SECRET
jq -n --arg base "$SHABAAS_WEBHOOK_BASE" --arg key "$SHABAAS_WEBHOOK_SECRET" \
'{auth_key:$key,payment_agreement:($base+"/agreement"),payment_initiation:($base+"/payment"),direct_debit_accepted:($base+"/dd-accepted"),direct_debit_rejected:($base+"/dd-rejected")}' > webhook.json
curl --fail-with-body --silent --show-error \
-X POST "$SHABAAS_BASE_URL/api/public/webhooks" \
-H "Authorization: $SHABAAS_AUTHORIZATION" -H 'Content-Type: application/json' \
--data-binary @webhook.json
rm webhook.json
Replace the receiver placeholder before running. The schema requires all four callback URLs even though this guide exercises PayTo. Registration updates the merchant's webhook configuration: use a dedicated sandbox merchant or retain the existing receiver URLs. Expected: HTTP 200 with a successful save message. See webhook registration and notification examples. This guide uses the shared-secret header flow, not an assumed signature algorithm.
4. Create a sandbox PayTo agreement
curl --fail-with-body --silent --show-error \
-X POST "$SHABAAS_BASE_URL/api/public/payment_agreement" \
-H "Authorization: $SHABAAS_AUTHORIZATION" -H 'Content-Type: application/json' \
--data '{"payment_agreement":{"name":"Sandbox Customer","type":"email","pay_id":"sample@shabaas.com","maximum_amount":"10.00","frequency":"ADHO","number_of_transactions_permitted":5}}' \
> agreement.json
export SHABAAS_AGREEMENT_ID="$(jq -er '.data.payment_agreement_id' agreement.json)"
Expected: HTTP 200 and data.payment_agreement_id. Initial status can be initiated; creation does not prove approval. In the sandbox, cents .00 select the approval scenario. Do not use a real customer's PayID. See sandbox scenarios and create agreement.
5. Wait for the agreement to be active
curl --fail-with-body --silent --show-error --get \
"$SHABAAS_BASE_URL/api/public/payment_agreement" \
-H "Authorization: $SHABAAS_AUTHORIZATION" \
--data-urlencode "id=$SHABAAS_AGREEMENT_ID" > agreement-status.json
jq '.data | {payment_agreement_id,status}' agreement-status.json
Repeat this GET with a bounded backoff or inspect the agreement webhook. Continue only when data.status, compared without case sensitivity, is active. Stop on rejection, failure or cancellation. Do not repeatedly create agreements while waiting. See agreement status.
6. Initiate one payment with a persistent idempotency key
Create the key once for this logical payment. Save the key, merchant reference and exact request body in your application before submitting. Reuse them after a timeout; generate a new key only for a genuinely new payment.
export SHABAAS_IDEMPOTENCY_KEY="sandbox-$(python3 -c 'import uuid; print(uuid.uuid4())')"
export SHABAAS_MERCHANT_REFERENCE="$SHABAAS_IDEMPOTENCY_KEY"
jq -n --arg id "$SHABAAS_AGREEMENT_ID" --arg ref "$SHABAAS_MERCHANT_REFERENCE" \
'{payment_initiation:{payment_agreement_id:$id,amount:"1.00",merchant_reference:$ref,notes:"First sandbox payment"}}' > payment.json
curl --silent --show-error -D payment-headers.txt \
-X POST "$SHABAAS_BASE_URL/api/public/payment_initiation" \
-H "Authorization: $SHABAAS_AUTHORIZATION" -H 'Content-Type: application/json' \
-H "Idempotency-Key: $SHABAAS_IDEMPOTENCY_KEY" \
--data-binary @payment.json > payment-response.json
cat payment-headers.txt
jq . payment-response.json
Expected: an accepted result can be HTTP 200 or HTTP 202 while the outcome is unknown. A returned payment ID is an acknowledgement, not settlement. Persist data.payment_initiation_id when present. A 409 indicates the same key was used for a different body; inspect the original request rather than resubmitting as a new payment. Keys must contain 16-128 permitted characters. See payment initiation.
If no payment ID is available yet, repeat the same request with the same key and body to retrieve its known outcome. Do not rerun the key-generation line. Keep the request files until the outcome is reconciled. HTTP 200 with a business error or pending message must also be inspected.
7. Confirm the payment outcome
export SHABAAS_PAYMENT_ID="$(jq -er '.data.payment_initiation_id' payment-response.json)"
curl --fail-with-body --silent --show-error --get \
"$SHABAAS_BASE_URL/api/public/payment_initiation" \
-H "Authorization: $SHABAAS_AUTHORIZATION" \
--data-urlencode "id=$SHABAAS_PAYMENT_ID" > payment-status.json
jq '.data | {payment_initiation_id,status,settled,transfer}' payment-status.json
Compare the GET response with events recorded by your receiver. Normalise the case of status strings for comparison. ACSC with settled: true means payer funds cleared into the ledger. transfer: transferred is a separate indication that payout was sent to the merchant bank. An accepted request, webhook arrival or agreement approval alone does not prove either outcome. Sandbox timing and simulated outcomes are not production settlement guarantees.
Use bounded polling and stop on a terminal failure. If the sandbox remains pending beyond your test window, keep the identifiers and contact support with the environment, HTTP result and request time; omit credentials. See status retrieval and status definitions.
Completion checklist
- You obtained a sandbox bearer token without exposing the API key.
- You created an agreement and confirmed its active state.
- You persisted one idempotency key and request body for one payment.
- You captured the initiation ID and inspected its eventual status.
- Your HTTPS receiver recorded authenticated agreement/payment events.
- You distinguished collection confirmation from merchant bank payout.
These examples were checked against the documented schemas and backend source. They are not a recorded live sandbox test. Delete local response files when your test is complete and retain only the identifiers and evidence required by your application's policy.