Cash Payments

This guide will show you how to accept cash payments online with Pay Theory’s checkout as well as how to handle barcodes that are generated at checkout.

Before you start

To use cash you will need to make sure the transact function is enabled in order to accept cash payments online.

Transact function

---

Javascript

Using the transact function

This function is used to submit a payment to Pay Theory or generate a barcode using Pay Theory’s cash fields. It returns a Promise with the result or an error.

paytheory.js

//Amount passed in is in cents
const AMOUNT = 1000

// optionally provide details about the payor
const PAYOR_INFO = {
  "first_name": "Some",
  "last_name": "Body",
  "email": "somebody@gmail.com",
  "phone": "3335554444",
  "personal_address": {
    "city": "Somewhere",
    "country": "USA",
    "region": "OH,
  }
}

const BILLING_INFO = {
  name: "Some Body",
  address: {
    line1: "123 Street St",
    line2: "Apartment 17",
    city: "Somewhere",
    country: "USA"
  }
}

const PAYMENT_METADATA = {
  "student-name": "Pat Theodore"
};

// Parameters that you will pass into the transact function. More details below.
const TRANSACTING_PARAMETERS = {
  amount: AMOUNT,
  payorInfo: PAYOR_INFO,
  metadata: PAYMENT_METADATA, // optional
}

paytheory.transact(TRANSACTING_PARAMETERS)

The following are values that you can pass into the transact function to customize the payment. The only required key is amount.

Key	type	description
amount	int	It represents the amount to be charged in cents.
payorInfo	object	Refer to payor info here payorinfo

The function returns a Promise that will contain an object with a key of type. You can expect the following values for type:

Type	description
CASH	The transact call successfully generated a barcode and the barcode details will be in the body key.
ERROR	The transact call had an error while processing and the error details will be in the error key.

Cash response

This is the value of the body key in the response if the type is CASH:

While generating the Barcode it will use the geolocation to return a map url for the user's specific location. If this is the first time it has been requested the user will have the opportunity to accept or decline the request.

Key	type	description
barcodeURL	string	The url for the barcode image.
mapURL	string	The url for the map to find the retail locations to pay the barcode.

Error response

This is the value of the error key in the response if the type is ERROR:

Key	type	description
message	string	The error message.

---

Cash Fields

You can customize your cash fields based on your requirements and desired user experience. These fields are all required to collect cash information from the user.

javascript

<form>
<div id = "pay-theory-cash-name"></div>
<div id = "pay-theory-cash-contact"></div>
</form>

Apple

Step 1: Import the Swift Package

First, you need to add the PayTheory Swift package to your Xcode project:

1. In Xcode, go to File > Add Packages...
2. In the search bar, enter the following URL: https://github.com/pay-theory/pay-theory-ios
3. Select the PayTheory package when it appears in the search results.
4. Choose the branch you want to use. This would be your partner name and the environment you are targeting.

• For example, if you are a partner named start targeting the paytheory environment, you would select the start-paytheory branch.
• Your environment can be paytheory, paytheorystudy, or paytheorylab.

5. Click "Add Package" to import it into your project.

Step 2: Import PayTheory in Your Swift File

In any Swift file where you want to use PayTheory, add the import statement at the top:

import PayTheory

Step 3: Initialize the PayTheory Object

Now, you can initialize the PayTheory object with your API key. You can do this in your SwiftUI view:

import SwiftUI
import PayTheory

struct ContentView: View {
    let payTheory = PayTheory(apiKey: "your-api-key-here") { error in
        print("Error: \(error.error)")
    }

    // ... rest of your view code
}

DevMode

When testing in the sandbox environment, set devMode to true to bypass App Attestation. This is useful for testing in simulators but does not reflect the production environment. Always test with devMode set to false in sandbox before moving to production.

Step 4: Wrap Your View with PTForm

Wrap your main view content with the PTForm view provided by the SDK. This allows the custom text fields to access the necessary data:

var body: some View {
    PTForm {
        VStack {
            // Your form fields will go here
        }
    }
    .environmentObject(payTheory)
}

Step 5: Add Custom Text Fields for Card Details

Use the custom text fields provided by the SDK to capture cash details:

PTForm {
    VStack {
        PTAchAccountName()
        PTAchAccountNumber()
        PTAchRoutingNumber()
        PTAchAccountType()

        // Other form fields as needed
    }
}
.environmentObject(payTheory)

Step 6: Implement Payment Button

Add a button to initiate the payment process:

Button("Pay") {
    payTheory.transact(amount: 1000, paymentMethod: .cash) { response in
        switch response {
        case .barcode(let barcode):
            print("Barcode Generated: \(barcode.barcodeUrl)")
        case .error(let error):
            print("Error: \(error.error)")
        case .failure:
            print("Response not possible when running a cash payment")
        case .success:
            print("Response not possible when running a cash payment")
        }
    }
}

Async Versions Available

Both transact and tokenizePaymentMethod have async versions that you can use with Swift's structured concurrency:

Button("Async Pay") {
    Task {
        let response = await payTheory.transact(amount: 1000, paymentMethod: .cash)
        // Handle response
    }
}

Choose the version that best fits your app's architecture and your preferred coding style.

Complete Example

Here's a complete example putting it all together:

import SwiftUI
import PayTheory

struct ContentView: View {
    let payTheory = PayTheory(apiKey: "your-api-key-here") { error in
        print("Error: \(error.error)")
    }

    var body: some View {
        PTForm {
            VStack {
                PTCardName()
                PTCardNumber()
                PTExp()
                PTCvv()
                PTCardPostalCode()

                Button("Pay") {
                    payTheory.transact(amount: 1000, paymentMethod: .cash) { response in
                        switch response {
                        case .barcode(let barcode):
                            print("Barcode Generated: \(barcode.barcodeUrl)")
                        case .error(let error):
                            print("Error: \(error.error)")
                        case .failure:
                            print("Response not possible when running a cash payment")
                        case .success:
                            print("Response not possible when running a cash payment")
                        }
                    }
                }
            }
        }
        .environmentObject(payTheory)
    }
}

This quick start guide demonstrates how to import the PayTheory package, initialize the PayTheory object, use the PTForm wrapper, add custom text fields for cash details, and implement a payment button to process a transaction.

Remember to replace "your-api-key-here" with your actual PayTheory API key.

For more advanced usage and additional payment methods, please refer to the full SDK documentation.

Android

Android Guide Coming Soon

Our Android SDK is fully functional. If you would like to implement our Android SDK select the link below for more information.

View Android SDK Reference

---

Next Steps

You can also refer to different payment modes like ACH functionality and QRCode functionality.