Skip to main content
Aggregator merchants represent the businesses you process payments for. They sit under an aggregator, inherit its credentials, and must link to a Safepay-managed Raast merchant before you can move money on their behalf.
FieldTypeRequired?ExampleNotes
merchant_external_idstringYessec_0c3de397-441f-471f-bcd7-b6d948e1c307Stable identifier you supply across environments.
ibanstringYesPK62ABPA0010000222380013Settlement IBAN for payouts.
namestringYesAcme Foods SaddarDisplay name shown in dashboards and reports.
enabledbooleanNotrueSet to true to activate immediately.
raast_merchant_idstringYesmer_eb2f5757-c0e4-4eb4-ad4b-2f4b671a84e2Links to a Safepay Raast merchant.
rate_card.ratecard_kindenumYesRateCardKind_fixedChoose the pricing model.
rate_card.fixed_rateintegerRequired for fixed3000Fee in paisa when using a fixed card.
rate_card.tax_regionstringNoPKRegion where the tax applies.
rate_card.tax_ratenumberYes0.1Tax rate applied to transactions.
Safepay performs KYC/KYB on every merchant. Payments remain blocked until the merchant status becomes ENABLED.
  • One aggregator merchant can link to only one Raast merchant.
  • A single Raast merchant can be shared across many aggregators. This lets a business entity use multiple aggregators without re-onboarding.

​
Create a merchant

Use the Aggregator Merchants API to create and link a merchant. Replace placeholders with your real values. The header name must match the OpenAPI security scheme (X-SFPY-AGGREGATOR-SECRET-KEY). 
curl --request POST "{{base_url}}/v1/aggregators/{{aggregator_id}}/merchants" \
  --header "X-SFPY-AGGREGATOR-SECRET-KEY: {{secret_key}}" \
  --header "Content-Type: application/json" \
  --data '{
    "merchant_external_id": "sec_0c3de397-441f-471f-bcd7-b6d948e1c307",
    "iban": "PK62ABPA0010000222380013",
    "name": "Acme Foods Saddar",
    "enabled": true,
    "raast_merchant_id": "{{raast_merchant_id}}",
    "rate_card": {
      "ratecard_kind": "RateCardKind_fixed",
      "fixed_rate": 3000,
      "tax_region": "PK",
      "tax_rate": 0.1
    }
  }'
Keep the returned data.token in your vault. Safepay refers to it as the aggregator_merchant_identifier when you create payments, QR codes, refunds, and payouts.

​
Merchant lifecycle

  1. Created - Safepay receives your request and assigns an ID.
  2. Pending checks - KYC/KYB validations run. Provide documentation if requested.
  3. Enabled - Payment, QR, and payout endpoints accept this merchant.
  4. Disabled - Safepay can suspend a merchant; payment requests will fail until re-enabled.
Re-use the List merchants and Get merchant endpoints to monitor these transitions during onboarding.

​
Key endpoints

EndpointPurpose
POST /v1/aggregators/{{aggregator_id}}/merchantsCreate an aggregator merchant.
GET /v1/aggregators/{{aggregator_id}}/merchantsList merchants with filters and pagination.
GET /v1/aggregators/{{aggregator_id}}/merchants/{{aggregator_merchant_id}}Read a single merchant.
PUT /v1/aggregators/{{aggregator_id}}/merchants/{{aggregator_merchant_id}}Update merchant details.
DELETE /v1/aggregators/{{aggregator_id}}/merchants/{{aggregator_merchant_id}}Disable or delete a merchant.

​
See also