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