URL scheme documentation and sample app for iOS
Using the custom SumUp URL scheme you can accept card payments from your iOS app or website through the SumUp iOS app.
To get started you will need to create a SumUp account and get an affiliate key in our Developer section.
If you are going to open the SumUp app from your own iOS app, SMPPaymentRequest is a convenient way to do so. See the sample app project for details and examples. You might also want to take a look at the SumUp iOS SDK to accept payments within your app.
If you are planning to open the SumUp app using a URL, please find the parameters below.
sumupmerchant://pay/1.0
| Key | Comment |
|---|---|
amount |
The amount to charge. Please use . as a decimal separator. |
currency |
The ISO 4217 code of currency to be charged. The currency needs to match the currency of the user that is logged into the SumUp app. For example EUR, GBP, BRL, CHF, PLN. |
affiliate-key |
Your affiliate key. It needs to be associated with the calling app’s bundle identifier. |
| Key | Comment |
|---|---|
title |
An optional title to be set on this transaction. |
callbackfail |
URL to be opened when the transaction fails. See Callback query parameters. |
callbacksuccess |
URL to be opened when the transaction succeeds. See Callback query parameters. |
receipt-email |
Prefills the email textfield when asking the customer whether he wants a receipts. |
receipt-mobilephone |
Prefills the phone number textfield when asking the customer whether he wants a receipts. |
foreign-tx-id |
An optional ID to be associated with this transaction. Please see our API documentation on how to retrieve a transaction using this ID. This ID has to be unique in the scope of a SumUp merchant account and its sub-accounts. It must not be longer than 128 characters and can only contain printable ASCII characters. Supported by SumUp app version 1.53 and later. Version 1.53.2 and later will append it to the callback URLs as a query parameter if provided. |
skip-screen-success |
To skip the screen shown at the end of a successful transaction, the skip-screen-success=true parameter can be used. When using the parameter your application is responsible for displaying the transaction result to the customer. In combination with the Receipts API your application can also send your own receipts, see API documentation for details. Please note success screens will still be shown when using the SumUp Air Lite readers. Supported by SumUp app version 1.69 and later. |
After the payment has been executed the SumUp app will open the callbacksuccess URL if the payment succeeded and the callbackfail URL if it did not. We will append the following query parameters if applicable:
| Key | Possible values | Comment |
|---|---|---|
smp-status |
success | The transaction has succeeded. |
| failed | The transaction has failed. | |
| invalidstate | The transaction can not be accepted as the SumUp app is in an invalid state. Please ask the user to open the SumUp app and make sure he’s ready to accept payments. | |
smp-tx-code |
TRANSACTION-CODE | The transaction code for this payment. Please see our API documentation to find out how to retreive details on this payment. Supported by SumUp app version 1.53 and later. |
foreign-tx-id |
YOUR-TX-ID | Only if provided. See Optional query parameters. Supported by SumUp app version 1.53.2 and later. |
If you are building your own iOS app you can use this class to conveniently open the SumUp app to accept a payment. It knows about all the URL parameters and makes accepting a payment as easy as:
SMPPaymentRequest *request;
NSDecimalNumber *amount = [NSDecimalNumber decimalNumberWithString:@"10.00"];
request = [SMPPaymentRequest paymentRequestWithAmount:amount
currency:@"EUR"
title:@"My title"
affiliateKey:@"YOUR-AFFILIATE-KEY"];
[request setCallbackURLSuccess:[NSURL URLWithString:@"samplepaymentapp://"]];
[request setCallbackURLFailure:[NSURL URLWithString:@"samplepaymentapp://"]];
/* This will open the following URL
* sumupmerchant://pay/1.0?amount=10.00¤cy=EUR&affiliate-key=YOUR-AFFILIATE-KEY
* &title=My%20title
* &callbackfail=samplepaymentapp%3A%2F%2F
* &callbacksuccess=samplepaymentapp%3A%2F%2F
*/
/* Optionally: Setting the option to skip success screens
* to add skip-screen-success=true to the URL
* Supported by SumUp app version 1.69 and later.
* [request setSkipScreenOptions:SMPSkipScreenOptionSuccess];
*/
[request openSumUpMerchantApp];