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" } ] }
]