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>"
  }
}