Account · Payments for Programmers

Payments for Programmers

Account

1200 words 6 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",
}

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.