# 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](https://payid.com.au/) 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](/openapi/april-public/payto/paytosendagreement).


```http request
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"
}
```


```json response
{
 "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](/openapi/april-public/payto/paytogetagreementstate) every few seconds until the returned state is `Active`.


```http request
GET https://api.sandbox.au.meetapril.io/payto/agreement?token=xxxx-one-off-agreement
Authorization: Bearer xxxx-auth-token
Accept: application/json
```


```json response
{
 "status": "Active"
}
```

**Step 3**: When the agreement is active, [create a payment token](/openapi/april-public/payment-tokens/createpaymenttoken) that is linked to the PayTo agreement.


```http request
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"
 }
}
```


```json response
{
 "PayToToken": {
   "paymentTokenId": "ptkn_ZisZ9bIZnTk_vU6A",
   "amount": {
     "minorCurrencyUnits": 5600,
     "currency": "AUD"
   },
   "surchargeAmount": 0,
   "agreementUid": "MPASOAV54NAUFQUOU54BDGIYUQIE",
   "accountIdentifierHint": "802950-2209****"
 }
}
```

**Step 4**: [Create an order](/openapi/april-public/orders/createorder) covering the payment amount and associated metadata.


```http request
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"
   }
 }
}
```


```json response
{
 "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](/openapi/april-public/orders/payorder) using the PayTo payment token.


```http request
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"
 }
}
```


```json response
{
 "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](/openapi/april-public/transactions/updatetransaction), using the `CreateRefund` action, specifying the refund amount (in cents).


```http request
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
 }
}
```


```json response
{
 "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](/openapi/april-public/payto/paytosendagreement).


```http request
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"
}
```


```json response
{
 "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](/openapi/april-public/payto/paytogetagreementstate) every few seconds until the returned state is `Active`.


```http request
GET https://api.sandbox.au.meetapril.io/payto/agreement?token=xxxx-open-agreement
Authorization: Bearer xxxx-auth-token
Accept: application/json
```


```json response
{
 "status": "Active"
}
```

**Step 3**: Save the open agreement by [creating an April payment source](/openapi/april-public/payment-sources/createpaymentsource).


```http request
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"
 }
}
```


```json response
{
 "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
}
```