1. Home
  2. Docs
  3. Data Subscriber API Documentation
  4. Tutorials
  5. Pay Me Back

Pay Me Back

In this tutorial you will write code that uses the PayMeBack product by Pentadata.

PayMeBack is the set of API endpoints that allows you to send money to your customers.

  • Create an object for your customer (in Pentadata, this is a “Person” object).
  • Link a bank account details (account number and routing) to that person.
  • Verify the account by matching the security micro-deposits.
  • Send the money!

The tutorial uses Python 3.9. The whole flow is contained in 5 simple functions used in the entry point:

if __name__ == '__main__':
    jwt = get_jwt(email, api_key)
    personid = add_user('Amanda', 'Dye', 'Amanda.Dye@outlook.com', jwt)
    paymeback_create(8726534872, 987634268, jwt, personid)
    paymeback_verify(personid, jwt, amount1=0.04, amount2=0.07)
    paymeback_send(personid, 4.99, jwt)
  • The first call is the login request to the Pentadata servers, which will return a JWT to be used in all other requests.
  • The last four functions implement the four steps described above.

The entire user-flow utilizes the Pentadata sandbox, which is a secure environment where you can test out all API calls and make your code ready for production. The data available in the sandbox is computer generated and does not reflect any real person, bank, card or merchant.

To subscribe for the sandbox, visit this page, then click on “Get API Key” at the center of the page.

Let’s now look at each of the functions used in the main more in details.

To start with, you will need to login:

email = '' # YOUR EMAIL
api_key = '' # YOUR API KEY

def get_jwt(email: str, api_key: str) -> str:
    """Login as API subscriber and returns the JWT."""
    headers = {
        'Content-Type': 'application/json'
    }
    payload = { 
        'email': email,
        'api_key': api_key
    }
    url = 'https://signal.pentadatainc.com/subscribers/login'
    response = requests.post(url, headers=headers, json=payload)
    if response.status_code != 200:
        logging.error('Cannot login %s', response.text)
        return None
    logging.debug('Login OK')
    jwt = response.json()['token']
    return jwt

Overall, this is a standard API call with JSON content that returns the a Json Web Token.

Next, you will need to create the Person object for your customer. You can write a very short function like the following:

def add_user(user_name: str,
             user_last: str,
             user_email: str,
             jwt: str) -> int:
    """Creates a Person object and returns the ID (int)."""

    headers = {
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {jwt}'
    }
    payload = {
        'first_name': user_name,
        'last_name': user_last,
        'email': user_email,
        'consent': 'Pentadata-sandbox'
    }
    endpoint = 'https://signal.pentadatainc.com/persons'
    response = requests.post(endpoint, headers=headers, json=payload)
    if not response.status_code == 201:
        logging.error('Cannot add user: %s', response.text)
    logging.debug('Added user %s', user_email)
    userid = response.json()['person_id']
    return userid

Pentadata is a 100% opt-in platform. This means that you will have to show that you have the user consent before doing anything with their profile: this is what the “consent” field is for in the request payload. In the sandbox you can pass any non-null string.

Next, you will need a function to create the bank account where you want to send money to, for that person.

def paymeback_create(account_no: int,
                     routing_no: int,
                     jwt: str,
                     personid: int,
                     account_type: str = 'checking') -> str:
    """Creates a PayMeBack method for a user."""

    headers = {
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {jwt}'
    }
    payload = {
        'account_no': account_no,
        'routing_no': routing_no,
        'account_type': account_type,
    }
    endpoint = f'https://signal.pentadatainc.com/persons/{personid}/pay'
    response = requests.post(endpoint, headers=headers, json=payload)
    if not response.status_code == 201:
        logging.error('Cannot add payment method: %s', response.text)
    logging.debug('Created payment for Person %s', personid)
    payid = response.json()['id']
    return payid

Once you are in production, you will obviously need to pass actual bank details to this function. In the sandbox, you can use any 10-digits account number and any 9-digits routing number.

After you’ve created the PayMeBack method for your customer, they have to prove that they are the owner of the account. This is done with the standard micro-deposits flow: we will deposit two small amounts in the bank account, and the user has to verify they have seen the amounts.

In practice, you will have to ask to the user what these amounts are, and then use our /pay-verify endpoint. Here is a function to call this endpoint:

def paymeback_verify(personid: int,
                     jwt: str,
                     amount1: float = 0.04,
                     amount2: float = 0.07) -> bool:
    """Verify a PayMeBack method for a user."""
    headers = {
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {jwt}'
    }
    payload = {
        'amount1': amount1,
        'amount2': amount2
    }
    endpoint = f'https://signal.pentadatainc.com/persons/{personid}/pay-verify'
    response = requests.post(endpoint, headers=headers, json=payload)
    if not response.status_code == 200:
        logging.error('Cannot verify payment method: %s', response.text)
        return False
    return True

In the sandbox, the correct amounts are 0.04 and 0.07 (that’s why they are the default values in the function above). You can then test both cases where the verification is successful and when it’s not.

Finally, after a PayMeBack method is verified, you can send money to your customer.

def paymeback_send(personid: int, amount: float, jwt: str):
    """Send money to a user via the PayMeBack API."""
    headers = {
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {jwt}'
    }
    payload = {'amount': amount}
    endpoint = f'https://signal.pentadatainc.com/persons/{personid}/pay-send'
    response = requests.post(endpoint, headers=headers, json=payload)
    if not response.status_code == 200:
        logging.error('Cannot send money: %s', response.text)
    else:
        logging.debug('Money sent')

And that’s it, your customer is on his way to receive money!

You can put all pieces together in a main method, and call the functions one after the other. Here’s a reproducible script that you can copy, paste and run, after you’ve got your API keys.

import logging
import requests

logging.basicConfig(format='%(asctime)s %(message)s', level=logging.DEBUG)

email = '' # YOUR EMAIL

api_key = '' # YOUR API KEY

def get_jwt(email: str, api_key: str) -> str:
    """Login as API subscriber and returns the JWT."""
    headers = {
        'Content-Type': 'application/json'
    }
    payload = {
        'email': email,
        'api_key': api_key
    }
    url = 'https://signal.pentadatainc.com/subscribers/login'
    response = requests.post(url, headers=headers, json=payload)
    if response.status_code != 200:
        logging.error('Cannot login %s', response.text)
        return None
    logging.debug('Login OK')
    jwt = response.json()['token']
    return jwt

def add_user(user_name: str,
             user_last: str,
             user_email: str,
             jwt: str) -> int:
    """Creates a Person object and returns the ID (int)."""
    headers = {
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {jwt}'
    }
    payload = {
        'first_name': user_name,
        'last_name': user_last,
        'email': user_email,
        'consent': 'Pentadata-sandbox'
    }
    endpoint = 'https://signal.pentadatainc.com/persons'
    response = requests.post(endpoint, headers=headers, json=payload)
    if not response.status_code == 201:
        logging.error('Cannot add user: %s', response.text)
    logging.debug('Added user %s', user_email)
    userid = response.json()['person_id']
    return userid

def paymeback_create(account_no: int,
                     routing_no: int,
                     jwt: str,
                     personid: int,
                     account_type: str = 'checking') -> str:
    """Creates a PayMeBack method for a user."""
    headers = {
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {jwt}'
    }
    payload = {
        'account_no': account_no,
        'routing_no': routing_no,
        'account_type': account_type,
    }
    endpoint = f'https://signal.pentadatainc.com/persons/{personid}/pay'
    response = requests.post(endpoint, headers=headers, json=payload)
    if not response.status_code == 201:
        logging.error('Cannot add payment method: %s', response.text)
    logging.debug('Created payment for Person %s', personid)
    payid = response.json()['id']
    return payid

def paymeback_verify(personid: int,
                     jwt: str,
                     amount1: float = 0.04,
                     amount2: float = 0.07) -> bool:
    """Verify a PayMeBack method for a user."""
    headers = {
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {jwt}'
    }
    payload = {
        'amount1': amount1,
        'amount2': amount2
    }
    endpoint = f'https://signal.pentadatainc.com/persons/{personid}/pay-verify'
    response = requests.post(endpoint, headers=headers, json=payload)
    if not response.status_code == 200:
        logging.error('Cannot verify payment method: %s', response.text)
        return False
    return True

def paymeback_send(personid: int, amount: float, jwt: str):
    """Send money to a user via the PayMeBack API."""
    headers = {
        'Content-Type': 'application/json',
       'Authorization': f'Bearer {jwt}'
    }
    payload = {'amount': amount}
    endpoint = f'https://signal.pentadatainc.com/persons/{personid}/pay-send'
    response = requests.post(endpoint, headers=headers, json=payload)
    if not response.status_code == 200:
        logging.error('Cannot send money: %s', response.text)
    else:
        logging.debug('Money sent')

if __name__ == '__main__':
    jwt = get_jwt(email, api_key)
    personid = add_user('Amanda', 'Dye', 'Amanda.Dye@outlook.com', jwt)
    paymeback_create(8726534872, 987634268, jwt, personid)
    paymeback_verify(personid, jwt, amount1=0.04, amount2=0.07)
    paymeback_send(personid, 4.99, jwt)

 

 

How can we help?