AppConnect

iOS and Android

AppConnect by PaySimple is an application for iOS and Android that enables easy payment collection from your app without the burden of PCI compliance.

AppConnect uses custom url schemes to transfer payment and customer data from your app.

If you are interested in integrating PaySimple AppConnect into your app, please contact our API Support Team at [email protected].

Launching PaySimple

The request you send will be url-encoded json sent as a query parameter value.

In order to initiate a payment with PaySimple you need to create a url and open it.

  • Scheme: paysimple-v1://
  • Host: make-payment
  • Query: data

 paysimple-v1://make-payment/?data=

Using the following JSON:

{
 "CallbackUrl": "yourappname://payment-complete",
 "AppName": "YourAppName",
 "Customer": {
 "FirstName": "John",
 "LastName": "Doe",
 },
 "Total": 10.99,
 "Description": "tree trimming"
}

The following url can be generated:

paysimple://make-payment/?data=%7B%22CallbackUrl%22%3A%22yourappname%3A%2F%2Fpayment-
complete%22%2C%22AppName%22%3A%22YourAppName%22%2C%22Customer%22%3A%7B
%22FirstName%22%3A%22Jeremy%22%2C%22LastName%22%3A%22Stevens%22%7D%2
C%22Total%22%3A10.99%2C%22Description%22%3A%22tree+trimming%22%7D

Once the url is created it just needs to be opened, this will then open the PaySimple application.

Completing the Payment

In order to finish the payment, PaySimple will return a response using a custom url scheme that your app registers and provides as a callback url in the request. The data will be a json url- encoded value of a query called data.

iOS

For iOS you need to add the CFBundleURLTypes to your Info.plist file such as:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleTypeRole</key>
    <string>Viewer</string>
    <key>CFBundleURLName</key>
    <string>com.yourappname.paymentcompleted</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>yourappname</string>
    </array>
  </dict>
</array>

You will also need to add the LSApplicationQueriesSchemes to your info.plist file exactly like this.

<key>LSApplicationQueriesSchemes</key>
<array>
 <string>paysimple-v1</string>
</array>

You may also want to reference Apple’s documentation for custom url schemes.

Android

For Android you need to add an intent filter to your manifest file such as:

<intent-filter>
   	<action android:name="android.intent.action.VIEW" />
   	<category android:name="android.intent.category.DEFAULT" />
   	<category android:name="android.intent.category.BROWSABLE" />
   	<data android:scheme="yourappname"
         android:host="payment-complete"/>
</intent-filter>

You may also want to reference Android’s documentation for deep linking.

Data Schema

Request Data

AppNameTypeRequiredDescription
AppNameStringYesThe name of your application. This will just be
used to display to your users
CallbackUrlStringYesThis is the url that PaySimple will use to append the payment response to and return
control back to your app.
CustomerCustomer ObjectNoCustomer information that will be tied to the payment.
DescriptionStringNoThis is an optional field that can be used for anything. It has a max length of 2048
characters.
TotalDecimalYesPossible Values: 0.01<Value<1999999.00
The total amount to bill the customer including taxes and fees.
ForceLogoutBoolNoDefaults to False.
If passed in as True then this will force the AppConnect application to logout on load, requiring the user to log back in. Can be used in conjunction with partner app logout sequence.
DisableCustomerAccessBoolNoDefaults to False.
If passed in as True the user is not able to change the customer during checkout process.
DisableAmountChangeBoolNoDefaults to False.
If passed in as True the user is not able to change the amount being charged during checkout process

Customer

PropertyTypeRequiredDescription
EmailStringNoEmail address for the customer.
FirstNameStringNoFirst name of the customer
IdIntNoPaySimple existing customer id.
If Id is passed, FirstName, LastName and Email will be treated as redundant since the CustomerID will be used to retrieve the account and that data will supersede all other customer data that was passed in.
LastNameStringNoLast name of the customer.

Response Data

PropertyTypeDescription
AmountPaidDecimalThe actual amount that was paid
CustomerIdIntegerThe PaySimple id of the customer that was associated to the payment
AccountIdIntegerThe PaySimple id of the customer payment account that was created/used for the payment
PaymentIdIntegerThe id of the payment that can be used to retrieve details about the transaction from PaySimple
PaymentTypePaymentTypeThe method of payment that was used
PaymentSubTypeStringPayment subtype, eg Visa, MasterCard for a CC payment or Checking, BusinessChecking, Savings for an ACH payment
PurchaseOrderNumberStringOriginal PO number that was passed in if present
StatusPaymentStatusThe status of the payment transaction
LastFourStringLast four digits of the payment account
ErrorMessageStringRelevant messaging regarding Payment Failure reason, Customer Error or App Launch error

PaymentStatus

NameDescription
AuthorizedInitial status for Credit Card payments
FailedPayment failed. Retrieve payment for more details
PostedInitial status for ACH payments
CancelledTransaction Cancelled before payment processing attempted

PaymentType

NameDescription
ACHA bank account
CreditCardA credit card

Error Handling

Launching PaySimple App Error Handling

Error TypeHandling
Total is incorrectly formatted or not presentPaySimple will use CallbackUrl to launch partner app with Status of “Cancelled” and ErrorMessage
Launch data is incorrectly formattedPaySimple will use CallbackUrl to launch partner app with Status of “Cancelled” and ErrorMessage
CallbackUrl is not presentIf the CallbackUrl for the partner app is not present, PaySimple will launch normally as if no data was passed in.
PaySimple app not foundIn the event that the PaySimple app is not found the partner app is responsible for handling a redirect to the app store to download the PaySimple app.

PaySimple in App Error Handling

Error TypeHandling
Customer Not FoundIf customer.id is passed in and not found by PaySimple, the user will be presented with 2 options:

1. Continue with sale without the customer loaded.
2. Cancel the sale and return to the partner app with response data:
- Status: Cancelled
- AmountPaid: 0
- CustomerId: 0
Swipe or Key Entered payment failedIf a card or ACH account is declined or makes a failed payment for any reason the user will be presented with 3 options:

1. Enter another card/Ach manually (key enter)
2. Swipe another card
3. Cancel the sale and return to the partner app with response data:
- Status: Failed
- AmountPaid: 0
- CustomerId: CustomerId that was used or
created
- AccountId: AccountId that was used or
created

Mobile Swipe Truth Table

Scenarios

1518