Account
1800 words 9 minutes
This details the general usage of the PayFunc Account functionalities.
Creating an Account
We strongly recommend creating accounts by integrating PayFunc Onboard. However, creating an account can also be done via a call to the account creation endpoint. When integrating through the endpoint, the account can be initialised with Customer Information and with payment methods if you already have tokenized card information.
Request
POST /account
Authentication: Bearer <public.api.key> | Bearer <private.api.key>
{
"number": "<your account identifier>",
"customer":"<Customer Information>",
"method": []
}Response
{
"id": "<PayFunc account identifier>",
"number": "<your account identifier>",
"customer": "<customer Information>",
"method": [],
"status": "created"
}Patch Account
To update the “limit”, “schedule” and “currency” fields of the Account, you can make a call to the patch account endpoint. Note that it is only possible to change the “currency” field of the account if the “total” field of the account equals 0.
This endpoint can also be called with an empty JSON object as body. In any case, calling this endpoint will fix deprecated accounts with invalid balance configurations and due dates.
Request
PATCH https://api.payfunc.com/account/<accountId>
{
"limit":"<updated limit>",
"currency":"<updated currency>",
"schedule":"<updated schedule>"
}Response
A successfull response will return an updated Account.
Balance
One of the main features of the account is to charge items against the balance of the account. For this there are three main features. Adding items to Balance, Adding funds to the Balance and settling the Balance.
Adding items to Balance
If a customer pays for an item with their balance, you can add that item to the balance using the account-balance-item endpoint. In this case just make a simple post request. The body of a valid request should either be a strictly positive, nonzero number, an Item or an array of Items.
Request
POST https://api.payfunc.com/account/<accountId>/balance
Authentication: Bearer <account.api.key> | Bearer <private.api.key>
{
"number":"<product number in your system>",
"name":"<name or description of product>",
"price":"<item price>",
"quantity":"<quantity>",
"unit":"<unit>",
"vat":"<vat>",
"rebate":"<rebate>"
}Response
A successfull response will return the updated Account.
Adding funds to Balance
Adding funds to the balance can be done via the regular Order Endpoint. To charge the balance of an account, specify the “charge” field of the account payment as “balance”. Once the payment is authorized, it will automatically credit the balance with the total of the payment and charge the order.
An Order that failed authorization will set the Account status to "pending" and retry authorization as specified in retrying failed account orders.
Request
POST https://api.payfunc.com/order
Authentication: Bearer <account.api.key> | Bearer <private.api.key>
{
"number": "your order identifier",
"items": "<Item or number indicating the charge to the balance>",
"currency": "<Currency 3 digit identifier>",
"account":"<accountIdentifier>",
"payment": {
"type": "account",
"charge": "balance"
}
}Response
A successful response will be as detailed in the Order Endpoint API.
Settling Balance
Calling this endpoint will settle the balance and move all Items that are charged towards the balance, but have not been settled yet, to an Order. Thus, all items charged to the balance will inevitably end up being added to an Order, so a receipt can be created for them.
A Request to this endpoint can either be made with a “private” authorization key or with the “account” authorization key. With the “account” authorization key you have to specify “me” as the account id, for “private” authorization specify the account id of the account you wish to settle or “all” if you want settle all accounts tied to the account.
If the balance already partially paid for the items specified in the “balance” field of the account, that amount will be added to the order as its own item.
The order will be an account order with the “charge” field in the “payment” field set to “balance” and will be automatically charged. Only a successful payment will update the “total” field of the account. A failed payment will retry authorization as specified in retrying failed account orders.
Request
DELETE https://api.payfunc.com/account/<accountId>/balance
Authentication: Bearer <account.api.key> | Bearer <private.api.key>Response
A response will be a json object specifying how many accounts updated their balance and how many accounts generated an error instead. If all accounts are correctly set up, the errors field should always equal 0.
{
"updated":"<amount of updated accounts>",
"errors":"<amount of accounts generating an error>"
}Change Customer Information
To change the customer information associated to an account make a PUT request to the following endpoint. A request to this endpoint can either be made with a “private” authorization key or with the “account” authorization key. With the “account” authorization key you have to specify “me” as the account id, for “private” authorization specify the account id of the account you wish to change.
The body of the request should be a valid Customer data type.
Request
PUT /account/<accountId>/customer
Authentication: Bearer <private.api.key> | Bearer <account.api.key>
{
"type": "organisation" | "person",
"identityNumber": "<identity number>",
"id": "<your customer Id>",
"name": "<customer name>",
"address": {
"street": "<street name>",
"zipCode": "<zip code>",
"city": "<city name>",
"countryCode": "<alpha 2 country code according to ISO 3166>"
},
"email": "<customer email>",
"phone": "<customer phone number>"
}Response
A successful response will equal the input.
Fetch Account Information
To fetch the account information a request to this endpoint can either be made with a “private” authorization key or with the “account” authorization key. With the “account” authorization key you have to specify “me” as the account id, for “private” authorization specify the account id of the account you wish to fetch.
Request
GET /account/<accountId>
Authentication: Bearer <private.api.key> | Bearer <account.api.key>Response
{
"id": "<PayFunc account identifier>",
"number": "<your account identifier>",
"method": "<Account Method Array>",
"subscription": "<Account subscription Array>",
"customer": {
"type": "organisation" | "person",
"identityNumber": "<identity number>",
"id": "<your customer Id>",
"name": "<customer name>",
"address": {
"street": "<street name>",
"zipCode": "<zip code>",
"city": "<city name>",
"countryCode": "<alpha 2 country code according to ISO 3166>"
},
"email": "<customer email>",
"phone": "<customer phone number>"
},
}List Accounts
To list all Accounts, just make a simple GET request with private authorization.
Request
GET /account
Authentication: Bearer <private.api.key> Response
A successful response will be an Array of Account objects.
[
{
"id": "<PayFunc account identifier>",
"number": "<your account identifier>",
"method": "<Account Method Array>",
"subscription": "<Account subscription Array>",
"customer": {
"type": "organisation" | "person",
"identityNumber": "<identity number>",
"id": "<your customer Id>",
"name": "<customer name>",
"address": {
"street": "<street name>",
"zipCode": "<zip code>",
"city": "<city name>",
"countryCode": "<alpha 2 country code according to ISO 3166>"
},
"email": "<customer email>",
"phone": "<customer phone number>"
},
},
]Create Account Page Login
To give access to the Account Page to the customer, you can send them a single use login Link via email. For this feature to be available, a customer email has to be set.
Request
To create such a login link send the following request to the account page login. A request to this endpoint can either be made with a “private” authorization key or with the “account” authorization key. With the “account” authorization key you have to specify “me” as the account id, for “private” authorization specify the account id.
POST /account/<accountId>/link
Authentication: Bearer <private.api.key> | <account.api.key> Response
A successful request made with account authorization will give an empty response. Regardless of authorization, an email including the single use login link will be sent to the customer email.
{
"url": "https://api.payfunc.com/account/<accountId>/link/0987654321098765",
"id": "0987654321098765",
"created": "2020-12-08T09:19:42.835Z",
"expires": "2020-12-11T09:19:42.835Z",
"key": "abc.def.ghi",
"contact": "[email protected]",
"used": false
}Account Methods
To add payment methods after account creation, refer the customer to the Account page, implement Payfunc Onboard for existing accounts or use the account methods endpoint to payment methods with already tokenized card information.
A request to this endpoint can either be made with a “private” authorization key or with the “account” authorization key. With the “account” authorization key you have to specify “me” as the account id, for “private” authorization specify the account id of the account you wish to change.
Request
POST /account/<accountId>/method
Authentication: Bearer <public.api.key> | Bearer <private.api.key>
{
"type": "token",
"card":"<tokenized card information>",
}Account Subscriptions
Adding a Subscription
Request
To add a subscription make a call to the subscription endpoint. The body can be any valid Subscription Creatable Object.
POST /account/<accountId>/subscription
Authentication: Bearer <private.api.key>
{
"number": "aaa-001",
"items": [
{
"name": "Basic Access",
"price": 42.00,
"vat": 25.00,
"quantity": 1
},
{
"name": "Premium Access",
"price": 100.00,
"vat": 25.00,
"quantity": 2
}
],
"currency": "SEK",
"schedule": {
"frequency": "quarterly",
"offset": [
2,
-1
]
},
"start": "2021-07-03",
"callback": "https://example.com/subscription"
}Response
The response will be an array containing all subscriptions on the account.
[
{
"start": "2021-07-03",
"number": "aaa-001",
"items": [
{
"name": "Basic Access",
"price": 42,
"vat": 25,
"quantity": 1
},
{
"name": "Premium Access",
"price": 100,
"vat": 25,
"quantity": 2
}
],
"currency": "SEK",
"schedule": {
"frequency": "quarterly",
"offset": [
2,
-1
]
},
"callback": "https://example.com/subscription",
"id": "test",
"due": "2021-09-30"
}
]Changing a Subscription
To change subscription data, make either a PUT or a PATCH request to the endpoint, specifying the 4 letter identifier of the subscription.
A PUT request will need to have a valid Subscription Creatable Object as the body and replace the subscription, while keeping the same subscription id.
A PATCH request requires a partial Subscription Creatable Object as the body and only update the fields that are present in the request body.
In both cases a future “due” date will be replaced by a calculated “due” date. As the backend will not set a “due” date past the “end” date, this endpoint can be used to end a subscription both immediately as well as at a future date.
Request
PUT | PATCH /account/<accountId>/subscription/<subscriptionId>
Authentication: Bearer <private.api.key>
{
"number": "aaa-001",
"items": [
{
"name": "Premium Access",
"price": 100.00,
"vat": 25.00,
"quantity": 3
}
],
"currency": "SEK",
"schedule": {
"frequency": "quarterly",
"offset": 2
},
"start": "2021-07-03",
"callback": "https://example.com/subscription"
}Response
The response will be an array with all subscriptions associated to the account, including the updated subscription.
Ending a Subscription
Ending a subscription will remove a future “due” date from the subscription and set the “end” date to the current date.
A request to this endpoint can either be made with a “private” authorization key or with the “account” authorization key. With the “account” authorization key you have to specify “me” as the account id, for “private” authorization specify the account id.
Request
DELETE /account/<accountId>/subscription/<subscriptionId>
Authentication: Bearer <private.api.key> | <account.api.key>Response
The response will be an array with all subscriptions associated to the account, including the updated subscription.