--- title: "Initiate split payment" method: POST path: "/v2/split-payments" tags: ["split-payments"] --- # Initiate split payment `POST /v2/split-payments` ## Request - Base URL: `https://api.sandbox.pawapay.io` - URL: `https://api.sandbox.pawapay.io/v2/split-payments` - Auth: HTTP bearer ## Headers - `Content-Digest` string, string: SHA-256 or SHA-512 hash of the request body. - `Signature` string, string: Signature of the request according to [RFC-9421](https://datatracker.ietf.org/doc/rfc9421/). - `Signature-Input` string, string: Signature input according to [RFC-9421](https://datatracker.ietf.org/doc/rfc9421/). - `Accept-Signature` string, string: Expected signature algorithm of the response according to [RFC-9421](https://datatracker.ietf.org/doc/rfc9421/). - `Accept-Digest` string, string: Expected digest algorithm of the response according to [RFC-9421](https://datatracker.ietf.org/doc/rfc9421/). ## Request body - SplitPaymentInitiationRequest - `splitPaymentId` string, uuid, required: A UUIDv4 based unique ID for this payment. We require you to provide the unique ID for all initiated payments to ensure you can always reconcile all payments. Please store this ID in your system before initiating the payment with PawaPay. - `payer` PayerOrRecipient, required: Details about the customer who is paying or receiving the payment. - `type` 'MMO', required: The type of account involved in the transaction. At the moment, only **MMO** is supported. - `accountDetails` AccountDetails, required - `phoneNumber` string, required: The phone number (MSISDN) of the customer paying or receiving payment. The format is described in [Wikipedia](https://en.wikipedia.org/wiki/MSISDN). Use [predict provider](/v2/api-reference/toolkit/predict-provider) to validate and sanitise the phone number. Phone number validation has following rules: * Only digits without whitespaces or any other separators or prefixes like '+'. * Should not start with zero. * Country code is mandatory. * Should not exceed or be less than the valid length of specified country. - `provider` string, required: The provider represents the mobile money operator or processor that can process payments. Find here a list of all the supported [providers](/v2/docs/providers). The [active configuration](/v2/api-reference/toolkit/active-configuration) endpoint provides the list of provider configured for your account. You can use the [predict provider](/v2/api-reference/toolkit/predict-provider) enpoint to predict the provider to use based on the phone number (MSISDN). - `clientReferenceId` string: A reference to an entity in your system that this payment relates to. For example, an invoice ID, customer ID etc. - `customerMessage` string: A short narration for the transaction. Depending on the 'provider', this message may be visible to the customer in the SMS receipt or within their transaction history. Defaults to your company name as registered on your PawaPay account trimmed to fit the length limitations. - `splits` SplitPayoutInitiationRequest[], required - `amount` string, required: The amount of the payment. Amount must follow below requirements or the request will be **rejected**: * Not all providers support decimals. Find which ones do from [providers](/v2/docs/providers) or dynamically using [active configuration](/v2/api-reference/toolkit/active-configuration) endpoint. * Transaction limits apply. Find them from the [Active Configuration](/v2/api-reference/toolkit/active-configuration) endpoint. * Leading zeroes are not permitted except where the value is less than 1. For any value less than one, one and only one leading zero must be supplied. - `recipient` PayerOrRecipient, required: Details about the customer who is paying or receiving the payment. - `type` 'MMO', required: The type of account involved in the transaction. At the moment, only **MMO** is supported. - `accountDetails` AccountDetails, required - `phoneNumber` string, required: The phone number (MSISDN) of the customer paying or receiving payment. The format is described in [Wikipedia](https://en.wikipedia.org/wiki/MSISDN). Use [predict provider](/v2/api-reference/toolkit/predict-provider) to validate and sanitise the phone number. Phone number validation has following rules: * Only digits without whitespaces or any other separators or prefixes like '+'. * Should not start with zero. * Country code is mandatory. * Should not exceed or be less than the valid length of specified country. - `provider` string, required: The provider represents the mobile money operator or processor that can process payments. Find here a list of all the supported [providers](/v2/docs/providers). The [active configuration](/v2/api-reference/toolkit/active-configuration) endpoint provides the list of provider configured for your account. You can use the [predict provider](/v2/api-reference/toolkit/predict-provider) enpoint to predict the provider to use based on the phone number (MSISDN). - `customerMessage` string: A short narration for the transaction. Depending on the 'provider', this message may be visible to the customer in the SMS receipt or within their transaction history. Defaults to your company name as registered on your PawaPay account trimmed to fit the length limitations. - `amount` string, required: The amount of the payment. Amount must follow below requirements or the request will be **rejected**: * Not all providers support decimals. Find which ones do from [providers](/v2/docs/providers) or dynamically using [active configuration](/v2/api-reference/toolkit/active-configuration) endpoint. * Transaction limits apply. Find them from the [Active Configuration](/v2/api-reference/toolkit/active-configuration) endpoint. * Leading zeroes are not permitted except where the value is less than 1. For any value less than one, one and only one leading zero must be supplied. - `currency` string, required: The currency in which the `amount` is specified. Format must be the ISO 4217 three character currency code in upper case. Read more from [Wikipedia](https://en.wikipedia.org/wiki/ISO_4217#Active_codes). Find the supported currencies for the [provider](/v2/docs/providers). The [active configuration](/v2/api-reference/toolkit/active-configuration) endpoint has all the providers configured for your account together with the supported currencies. - `metadata` TransactionMetadataRequestItem[]: A list of metadata that you can attach to the payment for providing additional context about the payment. For example, adding the channel from which the payment was initated, product ID or anything else that might help your operations team. Metadata will be included in: - In the dashboard on payment details pages - Financial statements as JSON object - Callbacks Metadata can be used when searching in the PawaPay Dashboard. Full value of the metadata field must be used for searches. Metadata will not be visible to the customer that is involved in this payment. Up to 10 metadata fields can be attached to a payment. - `additionalProperties` string: The metadata that you are attaching to the payment. For example `"orderId":"ORD-123456789"`. - `isPII` boolean: Indicates whether the field contains personally identifiable information. Used for compliance with GDPR or other relevant data privacy laws. ## Response `200` Request has valid payload. See `status` to confirm if the split payment was accepted for processing. - SplitPaymentCreationResponse - `splitPaymentId` string, uuid, required: A UUIDv4 based unique ID for this payment. We require you to provide the unique ID for all initiated payments to ensure you can always reconcile all payments. Please store this ID in your system before initiating the payment with PawaPay. - `status` 'ACCEPTED' | 'REJECTED' | 'DUPLICATE_IGNORED', required: The initiation status of the split payment: * `ACCEPTED` - The split payment has been **accepted** by PawaPay for processing. * `REJECTED` - The split payment has been **rejected**. See `failureReason` for details. * `DUPLICATE_IGNORED` - The split payment has been ignored as a duplicate of an already accepted split payment. Deduplication is based on `splitPaymentId`. - `created` string, date-time: The timestamp of when the payment was created in the PawaPay platform. Format defined by 'date-time' in RFC3339 section 5.6 from [IETF](https://tools.ietf.org/html/rfc3339#section-5.6) - `failureReason` SplitPaymentCreationFailureReason - `failureCode` 'INVALID_PARAMETER' | 'INVALID_RECIPIENT_FORMAT' | 'INVALID_CURRENCY' | 'INVALID_COUNTRY' | 'INVALID_AMOUNT' | 'INVALID_CORRESPONDENT' | 'DUPLICATE_METADATA_FIELD' | 'AMOUNT_OUT_OF_BOUNDS' | 'AMOUNT_TOO_SMALL' | 'AMOUNT_TOO_LARGE' | 'INVALID_PAYER_FORMAT' | 'INVALID_PHONE_NUMBER' | 'PROVIDER_TEMPORARILY_UNAVAILABLE' | 'SPLIT_PAYMENTS_NOT_ALLOWED' | 'PARAMETER_INVALID' | 'DUPLICATE_FIELD' | 'UNKNOWN_ERROR' | 'PAYOUT_EXCEEDS_DEPOSIT' | 'MISSING_SPLIT_AMOUNT' | 'MULTIPLE_SPLITS_NOT_SUPPORTED', required: Possible split payment initiation failure codes: * `INVALID_PARAMETER` - A parameter had an incorrect value. * `INVALID_RECIPIENT_FORMAT` - The recipient details are in an invalid format. * `INVALID_CURRENCY` - The currency is not supported with the selected provider. * `INVALID_COUNTRY` - All parties in the split payment must belong to the same country. * `INVALID_AMOUNT` - The amount format is invalid for the selected provider. * `INVALID_CORRESPONDENT` - The selected provider is invalid for this request. * `DUPLICATE_METADATA_FIELD` - A duplicate metadata field was found in the request. * `AMOUNT_OUT_OF_BOUNDS` - The amount is outside the supported transaction limits. * `AMOUNT_TOO_SMALL` - The amount is below the supported minimum. * `AMOUNT_TOO_LARGE` - The amount is above the supported maximum. * `INVALID_PAYER_FORMAT` - The payer details are in an invalid format. * `INVALID_PHONE_NUMBER` - The phone number is in the wrong format for the selected provider. * `PROVIDER_TEMPORARILY_UNAVAILABLE` - The provider is currently not able to process split payments. * `SPLIT_PAYMENTS_NOT_ALLOWED` - Split payments are not enabled for this provider on your PawaPay account. * `PARAMETER_INVALID` - A parameter value is invalid. * `DUPLICATE_FIELD` - The request contains a duplicate field. * `UNKNOWN_ERROR` - An unknown error has occured. * `PAYOUT_EXCEEDS_DEPOSIT` - The total split payout amount is greater than the deposit amount. * `MISSING_SPLIT_AMOUNT` - A split entry is missing its amount. * `MULTIPLE_SPLITS_NOT_SUPPORTED` - More than one split payout was provided in the request. - `failureMessage` string: Description of the reason for this failure. ## Other responses - `400`: Request was rejected due to incompatibility with PawaPay API specification. - `401`: Authentication failed. Make sure you have added the API token into the header. If using signatures, make sure they are valid. - `403`: Authorization failure. Please check your authentication token. - `500`: An unknown failure has occured. ## Changes - **2026-11-03** `4556d2ec2141`: 1 info - endpoint added [Operation history](https://skmtc.dev/pawapay/apis/pawapay-merchant-api-v2/changes/v2/split-payments/post.md) --- [API](https://skmtc.dev/pawapay/apis/pawapay-merchant-api-v2.md) - [All operations](https://skmtc.dev/pawapay/apis/pawapay-merchant-api-v2/llms.txt) - [OpenAPI document](https://skmtc.dev/pawapay/apis/pawapay-merchant-api-v2/revisions/4556d2ec2141?raw)