Reporting API

Functional Model

The BOPP payment network implements the following functional flow when processing payments from the BOPP Checkout.

When a payment is initiated by a Payee a PaymentRequest entity is created by the network. This PaymentRequest object is used throughout the lifetime of the payment and is used to provide an audit log of all actions associated with the payment request.

When a payment is initiated by a Payer the BOPP Network routes this call to the activator responsible for processing the payment request, this activator then provides the details of the request so that these can be processed by the Payer, who uses these to construct a PaymentInstruction which then routed by the network to the appropriate payment provider.

As the PaymentInstruction is processed by the payment network the statuses of the PaymentInstruction and associated PaymentRequest are updated which will cause updates to be sent to any subscribing application which is authorized to view the transactions on behalf of a party to the payment, (in this case the primary parties are the Payer and Payee, although additional parties such as a Seller, Buyer or Introducer may also be added).

When the PaymentInstruction is fully processed an object diagram like the one outlined above will have been created. This makes PaymentInstruction the payment processing history and associated payment reports available to the parties associated with the payment. The entities contained within this payment tree are the subject of this API document.

Payment Reports

While PaymentInstructions and PaymentRequests record the activities from the Payer and Payees as they make a payment the PaymentReports in the above diagram record the payment activity itself. PaymentReports are generated when the external payment system, e.g. the Bank in the case of Open Banking confirms that it has instructed and then executed the payment.

Network Entities

The section below provides additional information about the BOPP network entities which are used to implement the functional model outlined in the diagram above.

Properties and State

The BOPP payment network is designed for the distributed processing of multi-entity transactions. In order to maintain data consistency it operates an 'initiator-activator' model for client to server communications where the activating server is the single consistent maintainer of the state of any operational object.

This is reflected in the structure of the objects returned across its reporting API. Where an object can be operated on by both client and server the data elements it contains are split between Properties and State. Properties are set and changed by the client when it wants to request a server to make changes to an entity it is activating. The State reflects the authoritative state of the object from the servers perspective.

This model is reflected in the objects as they appear across the reporting API.

The reference pages for individual network entities provide more information about the specific Properies and State elements are provided on the reference documentation for each entity. The sections below highlight some key state elements which are used by the network activators to control payment processing and which can be used by report API clients to determine the processing status of particular payments.

Activation State

The ActivationState is a state machine value maintained in the State of all activation entities on the network, (PaymentRequests and PaymentInstructions) and indicated the overall completion status of the network entity.

State	Description	Comments
Pending	This entity has been created but has not yest started active processing.	Entities remain in a pending state until all validation and authorization has been completed.
Activated	This entity is authorized by all applicable parties and has started processing.	The entity is active, and will at some stage start to produce Activity Reports. Once an entity is in this state - receipt of a change or cancel event may not prevent some or all processing from being completed.
Cancelled	This entity was cancelled by its initiator before any activity was commenced.	This is a completed state - which indicated that nothing was done at the initiators request. See the notes on the complete state for caveats about completeness.
Rejected	This entity was rejected either upon creation or during its pending status by its activator or one of the associated parties.	This state will only be entered for entities that have been rejected before processing started - so rejected can be treated as final.
Complete	All processing on this entity has been completed.	In normal circumstances, no more changes will be accepted or Activity Reports generated.
Finalized	Processing on this entity has been completed, reconciled and confirmed.	The activity state of this entity has been complete and agreed by all parties and cannot be changed. Any remedy to activities created by a finalized entity can only be achieved by creating additional entities which reverse or compensate for them

Control Totals

In addition to the ActivationState above payment entities ((PaymentRequests and PaymentInstructions) also hold a series of control totals which give a numeric indication of the overall status of the payment as it is being processed.

PaymentRequest

Name	Description
Requested	The amount that has been requested from the payer(s). A null amount (not present) can be interpreted as an open pay request. If this amount is present then payment instructions which would cause this payment request to be over paid should be rejected.
Instructed	The total amount which has been instructed (by all PaymentInstrcutions) associated with this payment request
Received	The total amount received for this payment request (should match instructed when all payment instructions have successfully completed.
Remaining	The amount Requested minus the amount received. If the requested amount is null then this amount will also be null.

PaymentInstruction

Name	Description
Amount	The total amount which has been instructed by this payment instruction
Processed	The total amount processed for this payment request (should match amount when the payment instructions have successfully executed.
Remaining	The amount Requested minus the amount processed, unless the instruction is cancelled or expired in which case this will be 0

Report State

Where the processing of a payment instruction for third party payment provider is not instantaneous PaymentReports contain an additional state machine state which indicates their status from the perspective of the reporting entity.

Report State	Description
PendingAccept	The payment has been accepted by the processing party but has not yet completed validation and fraud checks and may be rejected prior to completion.
Accepted	The payment has been accepted by the processing party and fulfilled their local validation and be accepted for outgoing payment.
Confirmed	The payment as been received by the payers bank and payee’s bank and credited to their account.
Rejected	The payment processing has been rejected by the payer or payees bank and the payment has been cancelled.

API Types

The BOPP network provides three technical API's for receiving processing activity from the network:

• REST - intended for snapshot and historical reporting of the state of network entities including PaymentRequests, PaymentInstructions and PaymentReports.
• Webhook - for receiving network activity as it occurs during payment processing, this interface is event based and will receive a feed of all activity requests associated with entities of interest along with subsequent responses and reports.
• Websocket - this is a full peer connection to the network and can be used for both submitting status requests for network entities and receiving a streaming feed of network events as they occur.

The remainder of this document outlines the key technical characteristics of the REST and Webhook network interfaces. The websocket interface is described separately as the BOPP Peer API

REST API

The BOPP network API allows the retrieval of individual network entities as well as grouped entities based on query parameters. These retrievals are implemented via a GET request to the network. The general form of the URL used for this get request is as follows:

    GET https//api.$(network)/reporting/v1/$(resource)/$(resourceId)

or

    GET https//api.$(network)/reporting/v1/$(resource)?$(query params)

Where:

• network = the bopp network being addresses .io, .dev for prod and test
• resource = the payment network resource
• resourceId = the entity id of the resource to query

The currently supported resources are:

• paymentrequest returns details for a specific payment request.
  By default this will return only the direct elements of the payment request with no additional details, however if the query parameter instructions=true this response will additionally contain a nested set of the PaymentInstructions associated with this request. If the query parameter reports=true the PaymentReports will also be returned.
• paymentinstruction returns details for a specific payment instruction. By default this will return only the direct elements of the payment request with no additional details, however if the query parameter reports=true the response will additionally contain the paymentreport associated with this response.
• paylink returns details for the payment report associated with the passed in paylink. The options for this request have the same meaning as for the paymentrequest resource.

Query Parameters

The table below describes the currently supported query parameters

Name	Description
start	The datetime to start the resource query from
end	Optional the end datetime for the resource query, if absent and start is specified will default to now
parties	A list of parties used to filter the query. This parameter is of the form role=id. Where role specified the party role, such as payer or payee, and the id is the identifier of the party which plays that role.
instructions	If the resource is a paymentrequest or paylink and if this parameter is set true the payment instructions associated with the resource will be returned
reports	If the resource is a paymentrequest, paymentinstruction or paylink and if this parameter is set true the payment reports associated with this resource will be returned

Example Response

The data below provided an example return from a paymentrequest resource query.

{
  "@type": "https://dvschema.io/activation#ActivityReportStatusReport",
  "sequenceNumber": "8SeklY74PM2vA#85",
  "id": "cri:AYB0v05xPiWox2SANetqx9joaxbN8SVo",
  "activatingEntityId": "cri:AYB0v05zYYHz2lHXa91eUcNiwvRSrv9C",
  "properties": {
    "@type": "https://miapago.io/paylink/request#Properties",
    "activationLifetime": {
      "activationDate": "2020-09-21",
      "expiryDate": "2020-09-28"
    },
    "parties": {
      "payment:Payee": "cri:1lbmGYmQqGwatGHltCcMQEtta7HA",
      "payment:Subscriber": "cri:1lbmGYmQqGwatGHltCcMQEtta7HA"
    },
    "requestType": "Original",
    "paymentTerms": {
      "paymentTermsType": "Instant",
      "paymentTrigger": "OnInstruction",
      "amountTerm": {
        "termType": "FixedAmount",
        "properties": {
          "@type": "https://miapago.io/paymentterms/FixedAmountProperties"
        }
      },
      "paymentMethods": [
        {
          "methodType": "OpenBankingDomesticPayment",
          "properties": {
            "@type": "https://miapago.io/ob/domesticpayment/Properties",
            "endToEndIdentification": "BOPPButton",
            "name": "BOPP Dev Demo",
            "paymentReference": "2403252",
            "accountDID": "did:mia:ob:account:f626b0b3c68be017d4da49f3f68b103ba2340a602d8ef555bae119b58f0f031b",
            "subscriptionType": "Personal",
            "apikey": "cri:BDeMFufpBfhwJqIOpg8H7FxLvNYYSIgs"
          }
        }
      ]
    },
    "amount": {
      "value": "0.05",
      "unit": "ISO4217a:GBP"
    },
    "otpOptions": {
      "type": "TOTP",
      "calculationStatus": "Map",
      "mappingExpiry": "2021-09-27T09:26:38Z",
      "seed": "paylink://bopp.link/303u5",
      "digits": 6
    }
  },
  "state": {
    "@type": "https://miapago.io/paylink/request#State",
    "activationState": "Cancelled:Processed:NonePending",
    "initiationTime": "2021-09-27T09:27:35.815938709Z",
    "id": "cri:AYB0v05zYYHz2lHXa91eUcNiwvRSrv9C",
    "lastUpdateTime": "2021-09-27T09:27:40.028081942Z",
    "instructions": {
      "cri:AYB0v05zYYL5m2gIubCKEBMoN59Ov3hx": {
        "id": "cri:AYB0v05zYYL5m2gIubCKEBMoN59Ov3hx",
        "amount": {
          "value": "0.05",
          "unit": "ISO4217a:GBP"
        },
        "entityState": "Complete",
        "activityState": "Processed",
        "charges": {
          "value": "0",
          "unit": "ISO4217a:GBP"
        }
      }
    },
    "requested": {
      "value": "0.05",
      "unit": "ISO4217a:GBP"
    },
    "instructed": {
      "value": "0.05",
      "unit": "ISO4217a:GBP"
    },
    "received": {
      "value": "0.05",
      "unit": "ISO4217a:GBP"
    },
    "remaining": {
      "value": "1000",
      "unit": null
    },
    "limit": {
      "value": "1000",
      "unit": null
    },
    "reference": "2403252",
    "paylink": "paylink://bopp.link/303u5",
    "otpStatus": {
      "type": "TOTP",
      "issuer": "cri:1lbmGYmQqGwatGHltCcMQEtta7HA",
      "reference": "paylink://bopp.link/303u5",
      "epoch": "2021-09-27T09:26:30Z",
      "interval": 30,
      "calculationStatus": "Disabled"
    }
  },
  "reportState": [
    {
      "@type": "https://miapago.io/paymentreport#State",
      "reportState": "Activated",
      "initiationTime": "2021-09-27T09:27:33.369387865Z",
      "id": "cri:AYB0v061hNzcVshkfAX8Oj5RJPpXODMI",
      "lastUpdateTime": "2021-09-27T09:27:35.905713893Z",
      "activityDate": "2021-09-27",
      "activityTime": "2021-09-27T09:27:33.368765791Z",
      "executorId": "cri:4yJi0hw3wP1YH0IeFiQ1bx5My7VxIhRDMTc13Y1b0vbKC3Y00klXDeT78Zgp0QpLD7lBDJ8WO7v4s0dSk",
      "executingEntityId": "cri:AYB0v05zYYHz2lHXa91eUcNiwvRSrv9C",
      "parties": {
        "payment:Payee": "cri:1lbmGYmQqGwatGHltCcMQEtta7HA",
        "payment:Payer": "cri:NTgRQ2DIfWWuQIlromAFnR",
        "payment:Subscriber": "cri:1lbmGYmQqGwatGHltCcMQEtta7HA"
      },
      "amount": {
        "value": "0.05",
        "unit": "ISO4217a:GBP"
      },
      "charges": {
        "value": "0",
        "unit": "ISO4217a:GBP"
      },
      "reference": "2403252"
    }
  ],
  "timestamp": "2021-09-27T10:50:44.213691421Z",
  "possibleResend": false
}

Webhook API

Webhooks can be initiated by POSTing a webhook request to the network reporting API.

Create Webhook

    POST https//api.$(network)/reporting/v1/webhook

The body of the post request should be a json message which contains the following elements

Name	Description
url	The URL of the webhhook to be called. This URL must be addressable by the BOPP network and should process POST requests.
resource	The resource PaymentRequest, PaymentInstruction, PaymentReport to be received
states	A comma separated list of state triggers which will cause the webhook to be called
parties	A Map of { partyrole: partyId } values which specify the parties which will trigget this webhook

The return from this post method will return a webhookid which can be used to update or remove the webhook as specified below.

Update Webhook

Calling this method will cause the webhook to be updated. The body of this request should be the same as for the POST request above.

    PUT https//api.$(network)/reporting/v1/webhook/$(webhookId)

Remove Webhook

This method will cause the webhook to be deleted. Once completed no further calls will be made to the webhook.

    DELETE https//api.$(network)/reporting/v1/webhook/$(webhookId)