Overview

An Order is a container that manages the user interface flow for payments and agreements. When you create an order, you receive a unique token and a URL to the Payment Window where customers can complete their transactions.

Order Flow

1. Create Order - POST to create an order with payment/agreement details
2. Redirect Customer - Send customer to the UserInputUrl from the response
3. Customer Completes - Customer completes payment/agreement in Payment Window
4. Redirect Back - Customer is redirected to your AcceptUrl or CancelUrl

Order States

API Endpoints

Get All Orders

Retrieve all orders with optional status filtering.

GET https://api.farpay.io/v2/orders

Query Parameters:

• status (optional) - Filter by order status (100, 200, 300, 400, 500, 600, 700)

Response Example:

[
  {
    "Token": "abc123",
    "ExternalID": "your-reference-001",
    "AcceptUrl": "https://company.com/accept",
    "CancelUrl": "https://company.com/cancel",
    "CallbackUrl": "https://company.com/callback",
    "Lang": "en",
    "Status": "New",
    "Customer": {
      "CustomerNumber": "12345",
      "CustomerName": "John Smith",
      "CustomerEmail": "[email protected]"
    },
    "Payment": {
      "Amount": 49.95,
      "Currency": "DKK",
      "Description": "Monthly subscription",
      "Reference": "PAY-REF-001"
    },
    "Created": "2023-01-15T10:30:00Z"
  }
]

Get Single Order

Retrieve detailed information for a specific order.

GET https://api.farpay.io/v2/orders/{token}

Parameters:

• token (path) - The order's unique token

Create Order

Create a new order for payment or agreement creation.

POST https://api.farpay.io/v2/orders

Order Scenarios

Scenario 1: Payment Only

Use when customer should pay an amount without creating an agreement.

Request Body:

{
  "ExternalID": "ORDER-001",
  "AcceptUrl": "https://company.com/accept",
  "CancelUrl": "https://company.com/cancel",
  "CallbackUrl": "https://company.com/callback",
  "Lang": "da",
  "Agreement": 0,
  "Customer": {
    "CustomerNumber": "12345",
    "CustomerName": "John Smith",
    "CustomerEmail": "[email protected]"
  },
  "Payment": {
    "Amount": 49.95,
    "Currency": "DKK",
    "Description": "Monthly subscription payment",
    "Reference": "PAY-REF-001"
  }
}

Scenario 2: Agreement Required

Use when customer must create an agreement (with or without payment).

With Payment:

{
  "ExternalID": "ORDER-002",
  "AcceptUrl": "https://company.com/accept",
  "CancelUrl": "https://company.com/cancel",
  "CallbackUrl": "https://company.com/callback",
  "Lang": "da",
  "Agreement": 1,
  "Customer": {
    "CustomerNumber": "12345",
    "CustomerName": "John Smith",
    "CustomerEmail": "[email protected]"
  },
  "Payment": {
    "Amount": 49.95,
    "Currency": "DKK",
    "Description": "Initial payment",
    "Reference": "PAY-REF-002"
  }
}

Agreement Only:

{
  "ExternalID": "ORDER-003",
  "AcceptUrl": "https://company.com/accept",
  "CancelUrl": "https://company.com/cancel",
  "CallbackUrl": "https://company.com/callback",
  "Lang": "da",
  "Agreement": 1,
  "Customer": {
    "CustomerNumber": "12345",
    "CustomerName": "John Smith",
    "CustomerEmail": "[email protected]"
  }
}

Scenario 3: Optional Agreement

Use when customer should pay an amount with the option to create an agreement.

{
  "ExternalID": "ORDER-004",
  "AcceptUrl": "https://company.com/accept",
  "CancelUrl": "https://company.com/cancel",
  "CallbackUrl": "https://company.com/callback",
  "Lang": "da",
  "Agreement": 2,
  "Customer": {
    "CustomerNumber": "12345",
    "CustomerName": "John Smith",
    "CustomerEmail": "[email protected]"
  },
  "Payment": {
    "Amount": 49.95,
    "Currency": "DKK",
    "Description": "Monthly payment",
    "Reference": "PAY-REF-004"
  }
}

Order Properties

Required Properties

Optional Properties

Customer Object

Payment Object

Payment Type Filtering

Restrict available payment methods using the PaymentTypes property:

Example: "PaymentTypes": "bs,card" - Only Betalingsservice and cards available

Order Response

All order creation requests return the same response structure:

{
  "Status": "New",
  "Token": "abc123def456",
  "ExternalID": "ORDER-001",
  "AcceptUrl": "https://company.com/accept",
  "CancelUrl": "https://company.com/cancel",
  "CallbackUrl": "https://company.com/callback",
  "UserInputUrl": "https://app.farpay.io/payment/abc123def456",
  "Lang": "da",
  "PaymentTypes": "Mp,Invoice,Bs",
  "Agreement": 1,
  "Customer": {
    "CustomerNumber": "12345",
    "CustomerName": "John Smith",
    "CustomerEmail": "[email protected]"
  },
  "Payment": {
    "Amount": 49.95,
    "Currency": "DKK",
    "Description": "Monthly subscription",
    "Reference": "PAY-REF-001"
  },
  "Created": "2023-01-15T10:30:00Z"
}

Update Order

Update customer information for an existing order in "PendingCustomerNumber" state.

PUT https://api.farpay.io/v2/orders

Request Body:

{
  "Token": "abc123def456",
  "Customer": {
    "CustomerNumber": "12345",
    "CustomerName": "John Smith",
    "CustomerEmail": "[email protected]"
  }
}

Best Practices

1. External IDs: Use meaningful, unique identifiers for tracking orders
2. URLs: Ensure AcceptUrl and CancelUrl are accessible and handle responses properly
3. Language: Set appropriate language for your customer base
4. Payment Types: Restrict payment methods when appropriate to simplify customer choice
5. Error Handling: Implement proper error handling for all redirect URLs

Integration Flow

1. Create Order - POST order details to create payment flow
2. Redirect Customer - Send customer to UserInputUrl from response
3. Customer Completes - Customer completes payment/agreement in Payment Window
4. Handle Response - Customer redirected to AcceptUrl or CancelUrl
5. Process Result - Handle success/failure in your application

Related Resources

• Customers - Manage customer information
• Agreements - Handle payment instruments
• Payments - Track payment history

Orders

The Orders-endpoint is used to manage the creation and maintainance of Agreements and Payments that require a user/customer interaction.

The order is the term, that controls the user-interface-flow, enabling the user to handle the given task at hand. A full screen-to-process flow is found in FarPay Payment Window.

To have a user create a new Agreement or Payment, you must first create an Order by posting a model to this endpoint. The returned result is an Order-result model, that includes a unique Token to reference the Order, and the UserInputUrl to the Payment Window.

Subsequently after the order has been created, the user must be redirect to this Payment Window, specified in the UserInputUrl.

Now, after the user completion of the Agreement and/or the Payment, in the PaymentWindow, the user will be redirected back the the AcceptUrl that was defined when creating the Order. If the user cancels the process before it is compleated, FarPay will redirect the user to the CancelUrl.

The invoice endpoint https://api.farpay.io/{version}/orders gives you access to all your orders, and their state. Use Case scenarios are:

• List orders with optional status filter
• Single order (deep view)
• Create an order
• Update the order (With customer data)

Remark! that all requests must have an X-API-KEY and Accept mentioned in the header requests.

Order status

Get all orders

The endpoint is available from anHTTP_GET at https://api.farpay.io/{version}/orders, and can be filtered statusvalues mentioned in the table above.

Here is an example of a collection with an order - Remark that this is an example presented in JSON, and that the data can be presented as SOAP XML if requested...

[
  {
    "Token": "abc123",
    "ExternalID": "your reference",
    "AcceptUrl": "https://companyName.com/acceptUrl",
    "CancelUrl": "https://companyName.com/cancelUrl",
    "CallbackUrl": "https://companyName.com/callbackUrl",
    "Lang": "en",
    "Customer": {
       "CustomerNumber": "1234567890",
       "CustomerName": "Customer Name",
       "CustomerEmail": "[email protected]"
    },
    "Payment": {
      "Amount": 49.95,
      "Currency": "DKK",
      "Description": "First half month payment",
      "Reference": "YourPaymentReference"
    }
  }
]

Single order

Get an Order-object, based on a Token from an HTTP_GET at https://api.farpay.io/{version}/orders/{token} The order properties are the same as mentioned in the property table above.

Create order

When creating an Order, there are two properties that will manage the outcome of how the PaymentWindow render. First is the presence of an agreement that will hold the values:

• 0 - Meaning not applicable
• 1 - Required
• 2 - Optional

Remark that when an existing customer already has an agreement (with a specific type) attached, the Optional value (2), will not result in a render of the agreement possibility, when the agreement type wanted is the same type as the current. This precaution is made to mitigate the behavior that customers repeatedly complete the same registration over and over again.

Second property is the PaymentType that can reduce the flow options accordingly. When not specified, all available PaymentTypes will be exposed as valid options. A reduction can be specified with a comma seperated string with the wanted payment types:

  PaymentTypes = 'bs,card'

For Betalingsservice and MobilePay.

The available paymentTypes filters are:

• bs - Betalingsservice
• ls - Leverandørservice
• mp - MobilePay (both MobilePay Invoice and MobilePay Subscriptions)
• card - Dankort, Visa and/or MasterCard.

A Payment can also be You can also be include inside the Order, where you specify an Amount and Currency.

An Order can have the following combinations of Agreement and Payment:

A new Order can be created an HTTP_POST at https://api.farpay.io/{version}/orders. The order is created, and returned with a Token, as well as a link to the form, that the user can input the payment information in.

Here are the examples, from the scenarios above:

Scenario 1: Create order for a payment

This scenario should be used, when the customer should pay an amout, and not create an agreement.

A JSON payload:

{
  "ExternalID": "DOMAIN_REFERENCE-002",
  "AcceptUrl": "https://myCompany.com/accept",
  "CancelUrl": "https://myCompany.com/cancel",
  "CallbackUrl": "https://myCompany.com/callback",
  "Lang": "da",
  Agreement: 0,
  "Customer": {
     "CustomerNumber": "999918",
     "CustomerName": "My name and lastname",
     "CustomerEmail": "[email protected]"
  },
  "Payment": {
    "Amount": 4.50,
    "Currency": "DKK",
    "Description": "Betaling for den første måned",
    "Reference": "DOMAIN_BETALING_123456"
  }
}

Scenario 2: The agreement required, with a payment

This scenario covers two scenarios. In both cases the agreement is required, but in the first, the payment is required too.

JSON Payload, required agreement and required payment

This is typically used when the customer must create an agreement, as well as handling a payment - In some cases the initial payment.

{
  "ExternalID": "DOMAIN_REFERENCE-002",
  "AcceptUrl": "https://myCompany.com/accept",
  "CancelUrl": "https://myCompany.com/cancel",
  "CallbackUrl": "https://myCompany.com/callback",
  "Lang": "da",
  "Agreement": 1,
  "Customer": {
     "CustomerNumber": "999918",
     "CustomerName": "My name and lastname",
     "CustomerEmail": "[email protected]"
  },
  "Payment": {
    "Amount": 4.50,
    "Currency": "DKK",
    "Description": "Betaling for den første måned",
    "Reference": "DOMAIN_BETALING_123456"
  }
}

JSON Payload, required agreement and no payment:

This typically holds the scenario, where the customer must create an agreement only.

{
  "ExternalID": "DOMAIN_REFERENCE-002",
  "AcceptUrl": "https://myCompany.com/accept",
  "CancelUrl": "https://myCompany.com/cancel",
  "CallbackUrl": "https://myCompany.com/callback",
  "Lang": "da",
  "Agreement": 1,
  "Customer": {
     "CustomerNumber": "999918",
     "CustomerName": "My name and lastname",
     "CustomerEmail": "[email protected]"
  }
}

Scenario 3: Optional Agreement and Payment

This scenario plays out when there is an amount that must be paid. The user is presented with the option, in addition to the payment, also to create an agreement.

{
  "ExternalID": "DOMAIN_REFERENCE-002",
  "AcceptUrl": "https://myCompany.com/accept",
  "CancelUrl": "https://myCompany.com/cancel",
  "CallbackUrl": "https://myCompany.com/callback",
  "Lang": "da",
  "Agreement": 2,
  "Customer": {
     "CustomerNumber": "999918",
     "CustomerName": "My name and lastname",
     "CustomerEmail": "[email protected]"
  },
  "Payment": {
    "Amount": 4.50,
    "Currency": "DKK",
    "Description": "Betaling for den første måned",
    "Reference": "DOMAIN_BETALING_123456"
  }
}

Scenario 4: Amdatory Agreement, no payment

Use this when you only want the customer to create an agreement.

Remark, if you want to manage the process, and give the customer a single option - e.g. payment card, you would add the "PaymentTypes" = "card" to the root note. When "PaymenTypes" are not set, the customer will select between the available payment options, and then create the agreement on the selected type.

{
  "ExternalID": "DOMAIN_REFERENCE-002",
  "AcceptUrl": "https://myCompany.com/accept",
  "CancelUrl": "https://myCompany.com/cancel",
  "CallbackUrl": "https://myCompany.com/callback",
  "Lang": "da",
  "Agreement": 1,
  "Customer": {
     "CustomerNumber": "999918",
     "CustomerName": "My name and lastname",
     "CustomerEmail": "[email protected]"
  }
}

Result (all scenarios above)

Bear in mind that this result represents all the scenarios where the agreement can be present as an optional or a mandatory property, to that the Payment is only present when initially requested.

{
  "Status": "New | PendingPayment | PendingCustomer | Ok | Error | Canceled | Expired",
  "Token": "<token>",
  "ExternalID": "DOMAIN_REFERENCE-002",
  "AcceptUrl": "https://myCompany.com/accept",
  "CancelUrl": "https://myCompany.com/cancel",
  "CallbackUrl": "https://myCompany.com/callback",
  "UserInputUrl": "https://app.farpay.io/payment/<token>",
  "Lang": "da",
  "PaymentTypes": "Mp,Invoice,Bs",
  "Agreement": 0 | 1 | 2,
  "Customer": {
     "CustomerNumber": "999918",
     "CustomerName": "My name and lastname",
     "CustomerEmail": "[email protected]"
  },
  "Payment": {
    "Amount": 4.50,
    "Currency": "DKK",
    "Description": "Betaling for den første måned",
    "Reference": "DOMAIN_BETALING_123456"
  },
  "Created": "2018-10-30T10:36:09.115Z"
}

Update Order

For clarity, earlier examples the Customer was included in the Create Order documentation above. But in fact, the customer is not required to be known at the point when the Order is created.

In these scenarios, the domain system will have the customer information later on the process and can therefore also propagate these information to the order for final completion. In this state (Pending Customer Number), which means that the order might be completed with the user interaction, relating to both payment and creating an agreement, it still lacks the actual customer. This endpoint provides exactly that! When the customer is updated, the order is processed as planned. The agreement data, and the paymentdata (if any) are propagated into the formal model and structure of a Customer, Agreement and Payment when applicable in the order.

The endpoint is available as a HTTP_PUT from https://api.farpay.io/{version}/orders where the the order must contain a customer, that can be formalized into a strong type customer. The values, that are received are:

• CustomerNumber
• CustomerName
• CustomerEmail

{
  "Token": "<token>",
  "Customer": {
    "CustomerNumber": "999918",
    "CustomerName": "My name and lastname",
    "CustomerEmail": "[email protected]"
  }
}