Endpoints¶

The API offers a few endpoints to allow for flexible queries of Payjoy data.

In this section you will find a list of all queries available using the PayJoy API.

List Clerks¶

Query:

curl 'https://partner.payjoy.com/v1/list-clerks.php?key=<apikey>'

Result:

{"valid":true,"clerks":[
  {"id":"5335","personUuid":"a42ae711-0b28-4281-8938-9068e98c1234","name":"DemoClerk1","phoneNumber":"16178994187","email":"demo1@clerk.com"},
  {"id":"5334","personUuid":"b42ae711-1b28-5281-9938-0068e98c1235","name":"DemoClerk","phoneNumber":"16178994187","email":"test1@clerk.com"},
  {"id":"5320","personUuid":"c42ae711-2b28-6281-0938-1068e98c1236","name":"Demo InstallClark","phoneNumber":"16178994187","email":"demo1@clerk.com"}
]}

List Merchants¶

Query:

curl 'https://partner.payjoy.com/v1/list-merchants.php?key=<apikey>'

Result:

{"valid":true,"merchants":[
  {"id":"851005","name":"DEMO","address":
    {"street":"679 3rd St","street2":null,"city":"Tallahassee","state":"FL",
    "postalCode":"","country":"US"},"phoneNumber":"555-555-5555"},
  {"id":"999888","name":"DEMO1","address":
    {"street":"55 E 3rd Ave","street2":null,"city":"San Mateo","state":"CA",
    "postalCode":"94401","country":"US"},"phoneNumber":"505-505-5055"},
  {"id":"1000201","name":"DEMO2","address":
    {"street":"679 3rd St","street2":null,"city":"San Francisco","state":"CA",
    "postalCode":"94107","country":"US"},"phoneNumber":"555-555-5555"}
]}

Lookup Customer¶

Query:

curl 'https://partner.payjoy.com/v1/lookup-customer.php?key=<apikey>&customerLocator=<customerLocator>&fields=<fields>'

Note

customerLocator should be the customer’s phone number OR device tag OR an imei OR the customer id.
An imei is composed of decimal digits only, and may be 15 or 16 digits long.
fields Comma separated fields you want the endpoint to return. This parameter is optional. It can be: device.description

Result:

{ "valid": true,
  "customer": {
    "id": 4000005
    },
    "device": {
    "validThrough": 1560679200,
    "family": { "id": 3, "name": "Galaxy S6"},
    "imei": "339977",
    "model": {"id": 3, "makeModel": "SAMSUNG SM-G920P", "name": "Samsung Galaxy S6 (Boost/Sprint)"},
    "simNumber": "12345678901774567891",
    "lastSeen": 1560679200,
    "secureStatus": "Device Active And Secured",
    "description": "Blue device with 256 GB"
  },
  "financeOrder": { "currency": "USD", "downPayment": 100, "financeAmount": 200, "id": 4000004,
    "monthlyCost": 18, "months": 12, "pricePreTax": 300, "purchaseAmount": 300,
    "remainingBalance": 198, "time": 1482000000, "weeklyCost": 4},
  "paymentHistory": [
    {"amount": "18.00", "currency": "USD", "timestamp": "1487000002"}
  ],
  "paymentOptions": [
    {"amount": 198,"currency": "USD","type": "full"},
    {"amount": 18,"currency": "USD","type": "month"},
    {"amount": 4,"currency": "USD","type": "week"}
  ]
}

Lookup Cart¶

key Your private PayJoy partner API key. This parameter is required.
cartTag Cart tag that you are looking for. This parameter is required.
fields Comma separated fields you want the endpoint to return. This parameter is optional. It can be: customer.id, customer.name, customer.phoneNumber, customer.email, customer.address, customer.nationalId, device.description

Query:

curl 'https://partner.payjoy.com/v1/lookup-cart.php?key=<apikey>&cartTag=<cartTag>&fields=<fields>'

Result:

{
  "valid": true,
  "customer": {
    "id": ""1234,
    "name": "Customer Name Lastname",
    "phoneNumber": "0000000000",
    "email": "fake@email.com",
    "address": "fake address 1243",
    "nationalId": "000000558",
  },
  "cart": {
    "cartTag": "CARTTAGDEMO",
    "purchaseAmount": "3200.00",
    "financeAmount": "2156.00",
    "downPayment": "1044.00",
    "pricePreTax": 3000,
    "monthlyCost": "559.00",
    "weeklyCost": "129.00",
    "months": "6",
    "currency": "MXN"
  },
  "device": {
    "family": "Grand Prime Plus",
    "makeModel": "SAMSUNG SM-G532M",
    "description": "Blue device with 256 GB"
  }
}

List Transactions¶

Query:

curl 'https://partner.payjoy.com/v1/list-transactions.php?\
     key=<apikey>&starttime=<starttime>&endtime=<endtime>'

Result:

{
  "valid":true,
  "transactions":[
  {
    "type":"finance",
    "time":1482000000,
    "amount":200,
    "currency":"USD",
    "financeOrder":{"id":4000004,"purchaseAmount":300,
        "financeAmount":200,"downPayment":100,"pricePreTax":300,
        "monthlyCost":18,"weeklyCost":4,"months":12},
    "merchant":{"id":4000002,"name":"API Test Merchant"},
    "salesClerk":{"id":4000003,"name":"Demo Clerk1"},
    "device":{
      "phoneNumber":"15052111315",
      "simNumber":"12345678901774567891",
      "imei":"339977",
      "family":{"id":3,"name":"Galaxy S6"},
      "model":{"id":3,"makeModel":"SAMSUNG SM-G920P",
        "name":"Samsung Galaxy S6 (Boost\/Sprint)"}
    }
  },
  {
    "type":"cash",
    "time":1487000002,
    "amount":-18,
    "currency":"USD",
    "payment":{
        "id":4000008,
        "timestamp":1487000002,
        "amount":18},
    "financeOrder":{"id":4000004},
    "merchant":{
        "id":4000002,
        "name":"API Test Merchant"},
    "salesClerk":{
        "id":4000003,
        "name":"Demo Clerk1"}
  },
  {
    "type":"commission",
    "time":1602189749,
    "amount":1.8,
    "currency":"USD",
    "payment":{
        "id":5928003,
        "timestamp":1602189748,
        "amount":222},
    "financeOrder":{"id":4000004},
    "merchant":{
        "id":4000002,
        "name":"API Test Merchant"}
  },
  {
    "type":"adjustment",
    "time":1611085486,
    "amount":18,
    "currency":"USD",
    "adjustment":{
        "id":8884,
        "type":"payment",
        "notes":"Return adjustment for payment: 4000008"},
    "merchant":{
        "id":4000002,
        "name":"API Test Merchant"}
  },
  {
    "type":"adjustment",
    "time":1611085490,
    "amount":-1.8,
    "currency":"USD",
    "adjustment":{
        "id":8885,
    "type":"commission",
    "notes":"Return commission adjustment for payment: 4000008"},
    "merchant":{
        "id":4000002,
        "name":"API Test Merchant"}
  }]
}

Record In-Store Payment¶

key Your private PayJoy retail API key. This parameter is required.
merchantId PayJoy merchant unique identifier. A list of all stores can be found using the “List Merchants” endpoint. This parameter is required.
salesClerkId PayJoy clerk unique identifier. A list of all clerks can be found using the “List Clerks” endpoint. This parameter is required.
financeOrderId PayJoy unique identifier for the client’s contract. Customer information can be found using the “Lookup Customer” endpoint. This parameter is required.
amount The payment amount. This parameter is required.
currency ISO currency code. This parameter is required.

Query:

curl 'https://partner.payjoy.com/v1/record-customer-payment.php?\
key=abcde_fghij_dKktCpNrQSzm1_4coilc&merchantId=91234567&salesClerkId=1001234&\
financeOrderId=4001234&amount=4&currency=USD'

Result:

{
  "valid": true,
  "payment": {
    "id": "<integer, guaranteed to be unique>",
    "time": "<unix timestamp when payment was recorded>",
    "deviceTag": "<deviceTag of the device that received credit for the payment>",
    "remainingBalance": "<amount the customer needs to pay before the device is fully paid off>",
    "currency": "<currency of the remaining balance>",
    "nextPayment": "<unix timestamp when the device's lock will activate if payment is not received>",
    "fullyPaid": "<true if the device has been fully paid, false if a balance remains>"
  }
}