PayTo

Introduction

PayTo enables businesses to initiate payments directly from a customer's bank account, and have those payments settle and reconcile instantly. PayTo is a payment method that has been built on the New Payments Platform (NPP), and is available only within Australia.

A customer can set up a PayTo agreement using a BSB and account number, or by using a PayID alias which can be more convenient for the customer to use. PayID aliases can be the account holder's

  • telephone number (including domestic and international landline and mobile numbers)
  • email address
  • ABN, ACN, ARBN or ARSN
  • organisation Identifier

NOTE: If a customer does not have a registered PayID they can contact their bank. Visit PayID website for more information.

Agreement

There are two agreement types

  • One-Off Agreements
    • Single, one-time payments
    • No ongoing commitment or recurring transactions
  • Open Agreements
    • Recurring transactions with consent for future payments

API sequences

One-off agreement and payment

Step 1: First create the one-off agreement using the API endpoint PayTo Send Agreement.

requestresponse
Copy
Copied
POST https://api.sandbox.au.meetapril.io/payto/agreement
Authorization: Bearer xxxx-auth-token
Content-Type: application/json; charset=UTF-8
Accept: application/json

{
 "customerName": "Javier Milei",
 "customerAccIdentifier": {
   "Alias": {
     "aliasType": "Phone",
     "value": "+61419000000",
   }
 },
 "terms": {
   "AgreementRequestTermsOneOff": {
     "amount": {
       "amount": 5600,
       "currency": "AUD"
     }
   }
 },
 "purpose": "Mortgage"
}
Copy
Copied
{
 "token": "xxxx-one-off-agreement"
}

Record the token from the response as you will need it in the next step.

Step 2: Poll the agreement state every few seconds until the returned state is Active.

requestresponse
Copy
Copied
GET https://api.sandbox.au.meetapril.io/payto/agreement?token=xxxx-one-off-agreement
Authorization: Bearer xxxx-auth-token
Accept: application/json
Copy
Copied
{
 "status": "Active"
}

Step 3: When the agreement is active, create a payment token that is linked to the PayTo agreement.

requestresponse
Copy
Copied
POST https://api.sandbox.au.meetapril.io/tokens
Authorization: Bearer xxxx-auth-token
Content-Type: application/json; charset=UTF-8
Accept: application/json

{
 "CreatePayToToken": {
   "amount": {
     "minorCurrencyUnits": 5600,
     "currency": "AUD"
   },
   "agreementToken": "xxxx-one-off-agreement"
 }
}
Copy
Copied
{
 "PayToToken": {
   "paymentTokenId": "ptkn_ZisZ9bIZnTk_vU6A",
   "amount": {
     "minorCurrencyUnits": 5600,
     "currency": "AUD"
   },
   "surchargeAmount": 0,
   "agreementUid": "MPASOAV54NAUFQUOU54BDGIYUQIE",
   "accountIdentifierHint": "802950-2209****"
 }
}

Step 4: Create an order covering the payment amount and associated metadata.

requestresponse
Copy
Copied
POST https://api.sandbox.au.meetapril.io/orders
Authorization: Bearer xxxx-auth-token
Content-Type: application/json; charset=UTF-8
Accept: application/json

{
 "CreateOnlineOrder": {
   "referenceOrderId": "referenceOrderId-a0930b89-b72c-4043-95a9-a4f21d17a796",
   "amount": {
     "minorCurrencyUnits": 5600,
     "currency": "AUD"
   },
   "customerEmailAddress": "someone@test.com",
   "customerPhoneNumber": "+61401234567",
   "description": "Security light on rear door level 3",
   "items": [
     {
       "amount": {
         "minorCurrencyUnits": 120000,
         "currency": "AUD"
       },
       "description": "Labour",
       "quantity": 1
     },
     {
       "amount": {
         "minorCurrencyUnits": 5000,
         "currency": "AUD"
       },
       "description": "LED downlights",
       "quantity": 13
     }
   ],
   "billing": {
     "address": {
       "line1": "12 Brown Rd",
       "city": "Stanmore",
       "state": "NSW",
       "postalCode": "2011",
       "country": "AU"
     },
     "name": "Doug Chambers",
     "phoneNumber": "+61401234567"
   },
   "metadata": {
     "traderRating": 5,
     "stats": {
       "tradeCount": 622,
       "rating": "premo"
     },
     "coffee": "strong"
   }
 }
}
Copy
Copied
{
 "OnlineOrder": {
   "order": {
     "orderId": "ordr_ZisZ9bIZnTk_vU6C",
     "merchantId": "mcht_ZisZ5rIZnTk_vU5M",
     "referenceOrderId": "referenceOrderId-a0930b89-b72c-4043-95a9-a4f21d17a796",
     "amount": {
       "minorCurrencyUnits": 5600,
       "currency": "AUD"
     },
     ...
     "createdAt": "2024-04-26T03:05:25.435Z",
     "updatedAt": "2024-04-26T03:05:25.435Z"
   }
 }
}

Step 5: Pay for the order using the PayTo payment token.

requestresponse
Copy
Copied
POST https://api.sandbox.au.meetapril.io/orders/ordr_ZisZ9bIZnTk_vU6C/pay
Authorization: Bearer xxxx-auth-token
Content-Type: application/json; charset=UTF-8
Accept: application/json

{
 "PayByPayTo": {
   "paymentTokenId": "ptkn_ZisZ9bIZnTk_vU6A"
 }
}
Copy
Copied
{
 "PayOrderComplete": {
   "transactionId": "tran_ZisZ9bIZnTk_vU6E",
   "transactionStatus": "paid",
   "transactionDetails": {
     "purchaseDetails": {
       "orderId": "ordr_ZisZ9bIZnTk_vU6C",
       "merchantId": "mcht_ZisZ5rIZnTk_vU5M",
       "referenceOrderId": "referenceOrderId-a0930b89-b72c-4043-95a9-a4f21d17a796",
       "amount": {
         "minorCurrencyUnits": 5600,
         "currency": "AUD"
       },
     },
     "paymentMethod": {
       "paymentMethodType": "PayTo",
       "accountHint": "802950-2209****",
       "paymentStatus": "Settled",
       "paymentFailure": null
     },
     "serviceFees": {
       "variableAmount": 280,
       "fixedAmount": 40,
       "taxAmount": 32,
       "totalAmount": 352
     },
     ...
     "timelines": [
       {
         "eventType": "PaymentSucceed",
         "eventTime": "2024-04-26T03:05:25.810Z",
         "amount": 5600,
         "identifier": null
       }
     ]
   },
   "amount": 5600,
   "currency": "AUD",
   "surchargeAmount": 0,
   "payType": "payinfull"
 }
}

Issuing a partial or full refund

Step 1: Create the refund, using the CreateRefund action, specifying the refund amount (in cents).

requestresponse
Copy
Copied
PATCH https://api.sandbox.au.meetapril.io/transactions/tran_ZisZ9bIZnTk_vU6E
Authorization: Bearer xxxx-auth-token
Content-Type: application/json; charset=UTF-8
Accept: application/json

{
 "CreateRefund": {
   "refundAmount": 5600
 }
}
Copy
Copied
{
 "purchaseDetails": {
   "orderId": "ordr_ZisZ9bIZnTk_vU6C",
   "merchantId": "mcht_ZisZ5rIZnTk_vU5M",
   "referenceOrderId": "referenceOrderId-a0930b89-b72c-4043-95a9-a4f21d17a796",
   "amount": {
     "minorCurrencyUnits": 5600,
     "currency": "AUD"
   },
   "surchargeAmount": 0,
   "refundedAmount": 5600,
   "merchantName": "company-merchant-6f92307b-148f-4ad0-a70e-2c16ceebb2bc",
   "transactionId": "tran_ZisZ9bIZnTk_vU6E",
   "orderType": "online",
   "payType": "PayInFull",
   "description": "Security light on rear door level 3",
   "orderMetadata": {
     "traderRating": 5,
     "stats": {
       "tradeCount": 622,
       "rating": "premo"
     },
     "coffee": "strong"
   },
   "status": "refunded",
   "refundIds": [
     "rfnd_ZisZ9rIZnTk_vU6o"
   ],
   "disputeId": null,
   "disputeIds": [
   ],
   "paidOn": "2024-04-30",
   "createdAt": "2024-04-26T03:05:25.810Z",
   "updatedAt": "2024-04-26T03:05:26.217Z"
 },
 "paymentMethod": {
   "paymentMethodType": "PayTo",
   "accountHint": "802950-2209****",
   "paymentStatus": "Settled",
   "paymentFailure": null
 },
 "serviceFees": {
   "variableAmount": 280,
   "fixedAmount": 40,
   "taxAmount": 32,
   "totalAmount": 352
 },
 "customerDetails": null,
 "timelines": [
   {
     "eventType": "PaymentSucceed",
     "eventTime": "2024-04-26T03:05:25.810Z",
     "amount": 5600,
     "identifier": null
   },
   {
     "eventType": "PaymentRefunded",
     "eventTime": "2024-04-26T03:05:26.100Z",
     "amount": 5600,
     "identifier": "rfnd_ZisZ9rIZnTk_vU6o"
   }
 ]
}

Open agreement saved as payment source

A PayTo open agreement can be created and then saved as a re-usable payment source.

Step 1: First create the open agreement.

requestresponse
Copy
Copied
POST https://api.sandbox.au.meetapril.io/payto/agreement
Authorization: Bearer xxxx-auth-token
Content-Type: application/json; charset=UTF-8
Accept: application/json

{
 "customerName": "Javier Milei",
 "customerAccIdentifier": {
   "Bban": {
     "value": "802950-22090100"
   }
 },
 "terms": {
   "AgreementRequestTermsOpen": {
   }
 },
 "purpose": "Mortgage"
}
Copy
Copied
{
 "token": "xxxx-open-agreement"
}

Record the token from the response as you will need it in the next step.

Step 2: Optionally, poll the agreement state every few seconds until the returned state is Active.

requestresponse
Copy
Copied
GET https://api.sandbox.au.meetapril.io/payto/agreement?token=xxxx-open-agreement
Authorization: Bearer xxxx-auth-token
Accept: application/json
Copy
Copied
{
 "status": "Active"
}

Step 3: Save the open agreement by creating an April payment source.

requestresponse
Copy
Copied
POST https://api.sandbox.au.meetapril.io/sources
Authorization: Bearer xxxx-auth-token
Content-Type: application/json; charset=UTF-8
Accept: application/json

{
 "CreateSavedPaymentSource": {
   "sourceMethod": {
     "PayToMethod": {
       "agreementToken": "xxxx-open-agreement"
     }
   },
   "usageScope": "ScopeOrganisation"
 }
}
Copy
Copied
{
 "paymentSourceId": "psrc_ZisZ9LIZnTk_vU58",
 "customerId": "cust_ZisZ8LIZnTk_vU53",
 "merchantId": "mcht_ZisZ5rIZnTk_vU5M",
 "sourceMethod": {
   "PayToMethodResp": {
     "agreementUid": "MPA869OMPFPWQ1R75O65SW77H766",
     "accountIdentifierHint": "802950-2209****"
   }
 },
 "usageScope": null,
 "createdAt": "2024-04-26T03:05:24.966Z",
 "updatedAt": "2024-04-26T03:05:24.966Z",
 "legacyResp": null
}
Copyright © April Solutions 2023. All right reserved.