Order · Payments for Programmers

Payments for Programmers

Order

900 words 5 minutes

The order endpoint is the primary endpoint used for creating and administrating orders.

Creating

Card Account Payment

Request

POST https://api.payfunc.com/order
Authentication: Bearer <public.api.key>

{
	"number": "your order identifier",
	"items": 1337.42,
	"currency": "EUR",
	"payment": {
		"type": "account",
		"account": "<account id>"
	}
}

Response

{
	"id": "<order id>",
	"number": "your order identifier",
	"items": {
    "price": 18.37,
    "status": [
      "ordered"
    ]
  },
	"currency": "EUR",
	"created": "2019-01-01T13:37Z",
	"payment": {
		"reference": "1234abcd-12ab-34cd-56ef-1234567890ab",
		"account": "<account id>",
    "type": "card",
    "status": "created",
    "iin": "411111",
    "last4": "1111",
    "expires": [
				2,
				22
    ],
    "amount": 18.37,
    "currency": "EUR",
    "scheme": "visa",
		"service": "cardfunc",
		"card": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJjYXJkZnVuYyIsImlhdCI6MTYwMjc2MjA4MzY0MywiYXVkIjoicHJvZHVjdGlvbiIsInNjaGVtZSI6InZpc2EiLCJpaW4iOiI0MTExMTEiLCJsYXN0NCI6IjExMTEiLCJleHBpcmVzIjpbMiwyMl0sInR5cGUiOiJyZWN1cnJpbmciLCJjYXJkIjoieXBMaEJWdEMifQ.nz8JN_sig1Dowe_8-amJ4OdespKndOZbzqaLuwssMNNFjLuv1Vs-BidBYkCsiJDw0_hv8_3U1mvkaEN8O38ArarI6yIERGMMQhf-fOTdRp9RkNPtlrT89SLyPDkt0D0PiDM-UDXp1LFBHPEw-cgZad6t9XL3B-M3uy14SDRnPvVrUFe1zFFkg0t6XhEjNUt3imbesx5gU_3MDYJW0sk7OozC3r9VhM6HON-V5AeybOVpO4T3h9RdijqCeeWigTxXd3iW5TqDi2VIu-7VZJCACFWme1E43J3mTDt5nNjw7M6R1Nem94zqKQFTDBc2_Ft7J4pIQYeN36_lV5quoQQc5Q",
    "created": "2020-07-14T10:24:37+00:00"
	},
	"event": [
    {
      "type": "order",
      "date": "2020-10-22T08:14:57.358Z"
    }
	],
	"status": {
    "ordered": 18.37
	}
}

Retry Failed Account Payments

Failed account payments will be retried according to the “schedule” field of the Account Payment Creatable and the associated account will change its status to “pending”.
If the “schedule” field is not set, it will default to “[24,48]“. Between attempts, it will wait the specified amount of hours before automatically retrying. In case the last attempt fails, the account will change status to “suspended”.
To manually retry failed account payments use the retry endpoint.

Request

On private authorization, it will retry all pending and suspended orders associated to the merchant. On account authorization, it will retry all pending and suspended orders associated to the account. If all of the payments associated to the account succeeded, it will set its status to “active”.

PUT https://api.payfunc.com/retry
Authentication: Bearer <private.api.key> | Bearer <account.api.key>

Response

The response from the endpoint will include a json object specifying how many orders generated an error, how many orders remain unpaid and how many orders were paid in the attempt. If everything in the associated account is correctly configured, there should be no errors generated by the request.

{
	"errors":"<amount of orders generating errors on retrying>",
	"unpaid":"<amount of unpaid orders after retrying>",
	"paid":"<amount of orders paid in this retry attempt>"
}

Card Token Payment

Request

POST https://api.payfunc.com/order
Authentication: Bearer <public.api.key>
{
	"number": "your order identifier",
	"items": 7.42,
	"currency": "EUR",
	"payment": {
		"type": "card",
		"card": "<card token>"
	}
}

Response - Successful order creation

{
	"id": "<order id>",
	"number": "your order identifier",
	"items": {
    "price": 7.42,
    "status": [
      "ordered"
    ]
  },
	"currency": "EUR",
	"created": "2020-07-17T09:10:44.39Z",
	"payment": {
		"reference": "1234abcd-12ab-34cd-56ef-1234567890ab",
    "type": "card",
    "status": "created",
    "iin": "411111",
    "last4": "1111",
    "expires": [
				2,
				22
    ],
    "amount": 7.42,
    "currency": "EUR",
    "scheme": "visa",
		"service": "cardfunc",
		"card": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJjYXJkZnVuYyIsImlhdCI6MTYwMjc2MjA4MzY0MywiYXVkIjoicHJvZHVjdGlvbiIsInNjaGVtZSI6InZpc2EiLCJpaW4iOiI0MTExMTEiLCJsYXN0NCI6IjExMTEiLCJleHBpcmVzIjpbMiwyMl0sInR5cGUiOiJyZWN1cnJpbmciLCJjYXJkIjoieXBMaEJWdEMifQ.nz8JN_sig1Dowe_8-amJ4OdespKndOZbzqaLuwssMNNFjLuv1Vs-BidBYkCsiJDw0_hv8_3U1mvkaEN8O38ArarI6yIERGMMQhf-fOTdRp9RkNPtlrT89SLyPDkt0D0PiDM-UDXp1LFBHPEw-cgZad6t9XL3B-M3uy14SDRnPvVrUFe1zFFkg0t6XhEjNUt3imbesx5gU_3MDYJW0sk7OozC3r9VhM6HON-V5AeybOVpO4T3h9RdijqCeeWigTxXd3iW5TqDi2VIu-7VZJCACFWme1E43J3mTDt5nNjw7M6R1Nem94zqKQFTDBc2_Ft7J4pIQYeN36_lV5quoQQc5Q",
    "created": "2020-07-14T10:24:37+00:00"
  },
	"event": [
    {
      "type": "order",
      "date": "2020-07-17T09:10:44.391Z"
    }
	],
	"status": {
    "ordered": 7.42
	}
}

Response - Failing because of expired card token (valid only once and at most 1-2 hours after creation)

{
  "status": 400,
  "type": "invalid content",
  "content": {
    "type": "model.Card",
    "description": "Can't find valid and unexpired card pre-authorization"
  }
}

Response - Failing because of requirement that user authenticate the use of the card token through EMV 3D Secure.

{
  "status": 400,
  "type": "malformed content",
  "content": {
    "property": "payment.card",
    "type": "Card.Token",
    "description": "verification required",
    "details": {
      "visible": true,
      "method": "POST",
      "url": "<authentication service url>",
      "data": {
        "pareq": "<authentication service data payload>"
      }
    }
  }
}

Charge, Cancel & Refund

Change & Cancel

Once the end user has placed the order you can then charge or cancel the order. Charge is usually performed once the order has been fullfilled and cancel is done to cancel the order.

Cancel Single Order

Request

POST https://api.payfunc.com/order/<order id>/event
Authentication: Bearer <private.api.key>

{
	"type": "cancel"
}

Charge Single Order

Request

POST https://api.payfunc.com/order/<order id>/event
Authentication: Bearer <private.api.key>

{
	"type": "charge"
}

Partial Charge of Items

If an order contains specied items, it’s possible to charge a certain quantity of one or more items specifically.

Request

PATCH https://api.payfunc.com/order
Authentication: Bearer <private.api.key>

[{
	"id": "<order id>",
	"event": [
		{
			"type": "charge",
			"items": [
				{
					"name": "t-shirt",
					"price": 80,
					"quantity": 2,
					"unit": "st",
					"vat": 20
				},
				{
					"name": "gloves",
					"price": 160,
					"quantity": 1,
					"unit": "st",
					"vat": 40
				}
			]
		}
	]
}]

Partial Charge of Amount

An order that does not have items specified can be partially charged with a speficic amount.

Request

PATCH https://api.payfunc.com/order
Authentication: Bearer <private.api.key>

[{
	"id": "<order id>",
	"event": [
		{
			"items": 100,
			"type": "charge"
		}
	]
}]

Refund

An order that has been charged can be refunded. This is useful if the customer ends up returning the ordered items.

Refund Single Order

Request

POST https://api.payfunc.com/order/<order id>/event
Authentication: Bearer <private.api.key>

{
	"type": "refund"
}

Partial Refund of Items

If an order contains specied items, it’s possible to refund a certain quantity of one or more items specifically.

Request

PATCH https://api.payfunc.com/order
Authentication: Bearer <private.api.key>

[{
	"id": "<order id>",
	"event": [
		{
			"type": "refund",
			"items": [
				{
					"name": "t-shirt",
					"price": 80,
					"quantity": 2,
					"unit": "st",
					"vat": 20
				},
				{
					"name": "gloves",
					"price": 160,
					"quantity": 1,
					"unit": "st",
					"vat": 40
				}
			]
		}
	]
}]

Partial Refund of Amount

An order that does not have items specified can be partially refunded with a speficic amount.

Request

PATCH https://api.payfunc.com/order
Authentication: Bearer <private.api.key>

[{
	"id": "<order id>",
	"event": [
		{
			"items": 100,
			"type": "refund"
		}
	]
}]

Multiple Orders

The API allows for manipulating several orders with one single API call.

Request

PATCH https://api.payfunc.com/order/
Authentication: Bearer <private.api.key>

[
	{ "id": "<order id 0>", "event": [ { "type": "cancel" } ] }
	{ "id": "<order id 1>", "event": [ { "type": "charge" } ] }
	{ "id": "<order id 2>", "event": [ { "type": "charge" } ] }
]