https://github.com/sumup/sumup-ios-url-scheme
URL scheme documentation and sample app for iOS
https://github.com/sumup/sumup-ios-url-scheme
Last synced: about 1 year ago
JSON representation
URL scheme documentation and sample app for iOS
- Host: GitHub
- URL: https://github.com/sumup/sumup-ios-url-scheme
- Owner: sumup
- License: apache-2.0
- Created: 2015-09-09T15:20:44.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2025-01-06T09:59:33.000Z (over 1 year ago)
- Last Synced: 2025-03-30T22:41:37.555Z (about 1 year ago)
- Language: Objective-C
- Size: 242 KB
- Stars: 17
- Watchers: 178
- Forks: 5
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# SumUp custom URL scheme
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](https://me.sumup.com/developers).
If you are going to open the SumUp app from your own iOS app, [SMPPaymentRequest](#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](https://github.com/sumup/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.
## Base URL
`sumupmerchant://pay/1.0`
## Mandatory query parameters
| 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. |
## Optional query parameters
| 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](#Callback-query-parameters).|
|`callbacksuccess` | URL to be opened when the transaction succeeds. See [Callback query parameters](#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](https://sumup.com/integration#transactionReportingAPIs) 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](#Callback-query-parameters) 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](https://sumup.com/docs/rest-api/transactions-api) 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.*|
## Callback query parameters
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](https://sumup.com/integration#transactionReportingAPIs) 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](#optional-query-parameters). *Supported by SumUp app version 1.53.2 and later.*|
## SMPPaymentRequest
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:
```objc
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];
```
## Community
- **Questions?** Get in contact with our integration team by sending an email to integration@sumup.com.
- **Found a bug?** [Open an issue](https://github.com/sumup/sumup-ios-url-scheme/issues/new). Please provide as much information as possible.