Payment API

The BOPP payments REST API is available at the following network endpoint:

    https//api.$(network)/v1/payments/$(resource)

Where:

• network = the bopp network being addresses .io, .dev for prod and test
• resource = the payment network resource either request or instruction

To access the API the following header needs to be set:

Header	Value
x-bopp-api-key	Merchant API Key

Rest Methods

The BOPP payment API uses the following Rest methods to allow payment entities to be created, queried, changed and cancelled:

Payee

Method	Path	Description
POST	request	Initiates an internal create message for a PaymentRequest entity using the properties object passed in the body of the POST request. The POST will return the entity which results when the create request is applied and returned in a status response.
PUT	request/$(requestId)	Initiates an internal change message for the PaymentRequest entity referenced using the identifier contained in the path. The properties object passed in the body of the PUT request will be merged with the existing PaymentRequest properties. The PUT will return the entity which results when the change request is applied and returned in a status response.
DELETE	request/$(requestId)	Initiates an internal cancel message for the PaymentRequest entity referenced using the identifier contained in the path.
GET	request/$(requestId)	Returns the current status of the the PaymentRequest entity referenced using the identifier contained in the path.

Payer

Method	Path	Description
POST	instruction	Initiates an internal create message for a PaymentInstruction entity using the properties object passed in the body of the POST request. The POST will return the entity which results when the create request is applied and returned in a status response.
PUT	instruction/$(requestId)	Initiates an internal change message for the PaymentInstruction entity referenced using the identifier contained in the path. The properties object passed in the body of the PUT request will be merged with the existing PaymentInstruction properties. The PUT will return the entity which results when the change request is applied and returned in a status response.
DELETE	instruction/$(requestId)	Initiates an internal cancel message for the PaymentInstruction entity referenced using the identifier contained in the path.
GET	instruction/$(requestId)	Returns the current status of the the PaymentInstruction entity referenced using the identifier contained in the path.

Example Requests

POST https://api.$(network)/v1/payments/request

{
    "@type": "https://miapago.io/paylink/request/v0.1.0#Properties",
    "activationLifetime": {
            "activationDate": "2022-09-01"
    },
    "parties": {
        "payment:Payee": "cri:1lbmIdiG2dmZGQsJ23fpATis0wsN",
        "payment:Subscriber": "cri:1lbmIdiG2dmZGQsJ23fpATis0wsN"
    },
    "requestType": "Original",
    "paymentTerms": {
        "@type": "https://miapago.io/paymentterms/v0.1.0#RepeatPayment",
        "termsType": "Instant",
        "paymentTrigger": "EffectiveDate",
        "amount": {
            "@type": "https://miapago.io/paymentterms/terms/v0.1.0/FixedAmount",
            "amount": {
                "value": 1,
                "unit": "ISO4217a:GBP"
            }
        },
        "paymentMethods": [
            {
                "@type": "https://miapago.io/ob/paymentmethods/v0.1.0#DomesticPayment",
                "methodType": "OpenBankingPayment",
                "endToEndIdentification": "BOPPTransaction",
                "name": "No name",
                "paymentReference": "BOPPTransaction",
                "apikey": "cri:BDeMFufilAUlHur2x86W2lmFesfQbY8J",
                "accountDID": "did:mia:ob:account:008083b97e97fa8de03bb04cb15e0164b286ac0c9243ae12723084f1a584464f",
                "subscriptionType": "Personal",
                "payeeServiceId": "demo-aspsp"
            }
        ]
    }
}

Response

{
    "@type": "https://miapago.io/paylink/request/v0.1.0#PaylinkRequest",
    "originatorId": "PaylinkInitiator",
    "initiatorId": "PaylinkInitiator",
    "activatorId": "PaylinkRequestHandler",
    "activatingEntityId": "cri:2YOS8OR9G0uI1UCJOqk3NnGoMbseBU5",
    "state": {
        "@type": "https://miapago.io/paylink/request/v0.1.0#State",
        "activationState": "Activated:Accepted:PendingActive",
        "initiationTime": "2022-09-01T17:36:05.2080043Z",
        "id": "cri:2YOS8OR9G0uI1UCJOqk3NnGoMbseBU5",
        "lastUpdateTime": "2022-09-01T17:36:05.2085477Z",
        "requested": {
            "value": "1",
            "unit": "ISO4217a:GBP"
        },
        "instructed": {
            "value": "0",
            "unit": null
        },
        "received": {
            "value": "0",
            "unit": null
        },
        "remaining": {
            "value": "0",
            "unit": null
        },
        "reference": "BOPPTransaction",
        "requesterName": "test",
        "accountDID": "did:mia:ob:account:008083b97e97fa8de03bb04cb15e0164b286ac0c9243ae12723084f1a584464f",
        "paylink": "paylink://bopp.link/4kpzu"
    },
    "properties": {
        "@type": "https://miapago.io/paylink/request/v0.1.0#Properties",
        "activationLifetime": {
            "activationDate": "2022-09-01",
            "expiryDate": "2022-09-08"
        },
        "parties": {
            "payment:Payee": "cri:1lbmIdiG2dmZGQsJ23fpATis0wsN",
            "payment:Subscriber": "cri:1lbmIdiG2dmZGQsJ23fpATis0wsN"
        },
        "requestType": "Original",
        "paymentTerms": {
            "@type": "https://miapago.io/paymentterms/v0.1.0#RepeatPayment",
            "termsType": "Instant",
            "paymentTrigger": "EffectiveDate",
            "paymentMethods": [
                {
                    "@type": "https://miapago.io/ob/paymentmethods/v0.1.0#DomesticPayment",
                    "methodType": "OpenBankingPayment",
                    "payeeServiceId": "demo-aspsp",
                    "serviceId": "demo-aspsp",
                    "endToEndIdentification": "BOPPTransaction",
                    "name": "No name",
                    "paymentReference": "BOPPTransaction",
                    "accountDID": "did:mia:ob:account:008083b97e97fa8de03bb04cb15e0164b286ac0c9243ae12723084f1a584464f",
                    "subscriptionType": "Personal",
                    "apikey": "cri:BDeMFufku0GM0BAa8goVQC1xb9jQ015l"
                }
            ],
            "amount": {
                "@type": "https://miapago.io/paymentterms/terms/v0.1.0#FixedAmount",
                "amount": {
                    "value": "1",
                    "unit": "ISO4217a:GBP"
                }
            }
        }
    },
    "requestContext": {
        "lastAcceptedRequestId": "cri:7medwFpYKajslBRzzBJOuQWM",
        "lastRequestId": "cri:7medwFpYKajslBRzzBJOuQWM",
        "lastResponseId": "cri:2YOS8OR9mAsYWOnAlSBb93zPjwCII05"
    }
}

GET https://api.$(network)/payments/v1/request/cri:2YOS8OR9G...

Response

{
    "@type": "https://miapago.io/paylink/request/v0.1.0#PaylinkRequest",
    "originatorId": "PaylinkInitiator",
    "initiatorId": "PaylinkInitiator",
    "activatorId": "PaylinkRequestHandler",
    "activatingEntityId": "cri:2YOS8OR9G0uI1UCJOqk3NnGoMbseBU5",
    "state": {
        "@type": "https://miapago.io/paylink/request/v0.1.0#State",
        "activationState": "Activated:Processing:PendingChange",
        "initiationTime": "2022-09-01T17:36:05.2080043Z",
        "id": "cri:2YOS8OR9G0uI1UCJOqk3NnGoMbseBU5",
        "lastUpdateTime": "2022-09-01T17:47:13.7956878Z",
        "instructions": {
            "cri:2YOS8OR9G18KEjPe2FfHIb7ppAbEmzN": {
                "id": "cri:2YOS8OR9G18KEjPe2FfHIb7ppAbEmzN",
                "amount": {
                    "value": "1",
                    "unit": "ISO4217a:GBP"
                },
                "entityState": "Activated",
                "activityState": "Initialised",
                "charges": {
                    "value": "0.5",
                    "unit": "ISO4217a:GBP"
                }
            }
        },
        "requested": {
            "value": "1",
            "unit": "ISO4217a:GBP"
        },
        "instructed": {
            "value": "1",
            "unit": "ISO4217a:GBP"
        },
        "received": {
            "value": "0",
            "unit": null
        },
        "remaining": {
            "value": "1",
            "unit": "ISO4217a:GBP"
        },
        "reference": "BOPPTransaction",
        "requesterName": "test",
        "accountDID": "did:mia:ob:account:008083b97e97fa8de03bb04cb15e0164b286ac0c9243ae12723084f1a584464f",
        "paylink": "paylink://bopp.link/4kpzu"
    },
    "properties": {
        "@type": "https://miapago.io/paylink/request/v0.1.0#Properties",
        "activationLifetime": {
            "activationDate": "2022-09-01",
            "expiryDate": "2022-09-08"
        },
        "parties": {
            "payment:Payee": "cri:1lbmIdiG2dmZGQsJ23fpATis0wsN",
            "payment:Subscriber": "cri:1lbmIdiG2dmZGQsJ23fpATis0wsN"
        },
        "requestType": "Original",
        "paymentTerms": {
            "@type": "https://miapago.io/paymentterms/v0.1.0#RepeatPayment",
            "termsType": "Instant",
            "paymentTrigger": "EffectiveDate",
            "paymentMethods": [
                {
                    "@type": "https://miapago.io/ob/paymentmethods/v0.1.0#DomesticPayment",
                    "methodType": "OpenBankingPayment",
                    "payeeServiceId": "demo-aspsp",
                    "serviceId": "demo-aspsp",
                    "endToEndIdentification": "BOPPTransaction",
                    "name": "No name",
                    "paymentReference": "BOPPTransaction",
                    "accountDID": "did:mia:ob:account:008083b97e97fa8de03bb04cb15e0164b286ac0c9243ae12723084f1a584464f",
                    "subscriptionType": "Personal",
                    "apikey": "cri:BDeMFufku0GM0BAa8goVQC1xb9jQ015l"
                }
            ],
            "amount": {
                "@type": "https://miapago.io/paymentterms/terms/v0.1.0#FixedAmount",
                "amount": {
                    "value": "1",
                    "unit": "ISO4217a:GBP"
                }
            },
            "maxPayments": 10
        }
    },
    "requestContext": {
        "lastAcceptedRequestId": "cri:7medwFpYKajslBRzzBJOuQWM",
        "lastRequestId": "cri:7medwFpYKajslBRzzBJOuQWM",
        "lastResponseId": "cri:2YOS8OR9mBOKnjUuZBQyjLOMeMd26RW"
    }
}

POST https://api.$(network)/v1/payments/instruction

{
    "@type": "https://miapago.io/paymentinstruction/v0.1.0#Properties",
    "parties": {
      "payment:Payer": "cri:NTgRQ2DIfWWuQIlromAFnR"
    },
    "paymentTerms": {
      "@type": "https://miapago.io/paymentterms/v0.1.0#SinglePayment",
      "amount": {
        "@type": "https://miapago.io/paymentterms/terms/v0.1.0/FixedAmount",
        "amount": {
          "value": 1,
          "unit": "ISO4217a:GBP"
        }
      }
    },
    "paymentMethod": {
      "methodType": "BoppPaylink",
      "@type": "https://miapago.io/paylink/v0.1.0#PaymentMethod",
      "paylink": "{{paylink}}",
      "linkedMethod": {
        "@type": "https://miapago.io/ob/paymentmethods/v0.1.0#DomesticPayment",
        "methodType": "OpenBankingPayment",
        "endToEndIdentification": "BOPPTransaction",
        "name": "No name",
        "paymentReference": "BOPPTransaction",
        "accountDID": "did:mia:ob:account:008083b97e97fa8de03bb04cb15e0164b286ac0c9243ae12723084f1a584464f",
        "subscriptionType": "Personal",
        "apikey": "cri:BDeMFufilAUlHur2x86W2lmFesfQbY8J",
        "serviceId": "demo-aspsp"
      }
    }
  }
  

Response

{
    "@type": "https://miapago.io/paymentinstruction/v0.1.0#PaymentInstruction",
    "originatorId": "PaylinkInitiator",
    "originatingEntityId": "cri:2YOS8OR9G0uI1UCJOqk3NnGoMbseBU5",
    "initiatorId": "PaylinkInitiator",
    "activatorId": "PaylinkInstructionRouter-activator",
    "activatingEntityId": "cri:2YOS8OR9G18KEjPe2FfHIb7ppAbEmzN",
    "state": {
        "@type": "https://miapago.io/paymentinstruction/v0.1.0#State",
        "activationState": "Pending:Initialised:PendingAccept",
        "initiationTime": "2022-09-01T17:47:13.7433434Z",
        "id": "cri:2YOS8OR9G18KEjPe2FfHIb7ppAbEmzN",
        "lastUpdateTime": "2022-09-01T17:47:13.7684243Z",
        "parties": {
            "payment:Payee": "cri:1lbmIdiG2dmZGQsJ23fpATis0wsN",
            "payment:Subscriber": "cri:1lbmIdiG2dmZGQsJ23fpATis0wsN"
        },
        "paymentState": {
            "@type": "https://miapago.io/ob/paymentmethods/v0.1.0#State",
            "payeeName": "",
            "authorizationURL": "https://democonsentapp.netlify.app/democonsentapp?arg=?code=accept&state=7mgH2cfhidqT0i2iHwI4yaFd-consentid",
            "paymentConsent": "test",
            "paymentStatus": ""
        },
        "instructed": {
            "value": "1",
            "unit": "ISO4217a:GBP"
        },
        "processed": {
            "value": "0",
            "unit": "ISO4217a:GBP"
        },
        "remaining": {
            "value": "1",
            "unit": "ISO4217a:GBP"
        }
    },
    "properties": {
        "@type": "https://miapago.io/paymentinstruction/v0.1.0#Properties",
        "parties": {
            "payment:Payer": "cri:NTgRQ2DIfWWuQIlromAFnR"
        },
        "paymentTerms": {
            "@type": "https://miapago.io/paymentterms/v0.1.0#SinglePayment",
            "termsType": "Normal",
            "amount": {
                "@type": "https://miapago.io/paymentterms/terms/v0.1.0#FixedAmount",
                "amount": {
                    "value": "1",
                    "unit": "ISO4217a:GBP"
                }
            }
        },
        "paymentMethod": {
            "@type": "https://miapago.io/paylink/v0.1.0#PaymentMethod",
            "methodType": "BoppPaylink",
            "paylink": "paylink://bopp.link/4kpzu",
            "linkedMethod": {
                "@type": "https://miapago.io/ob/paymentmethods/v0.1.0#DomesticPayment",
                "methodType": "OpenBankingPayment",
                "serviceId": "demo-aspsp",
                "endToEndIdentification": "BOPPTransaction",
                "name": "No name",
                "paymentReference": "BOPPTransaction",
                "accountDID": "did:mia:ob:account:008083b97e97fa8de03bb04cb15e0164b286ac0c9243ae12723084f1a584464f",
                "subscriptionType": "Personal",
                "apikey": "cri:BDeMFufilAUlHur2x86W2lmFesfQbY8J"
            }
        }
    },
    "requestContext": {
        "lastAcceptedRequestId": null,
        "lastRequestId": "cri:7mgH2cfhidqT0i2iHwI4yaFd",
        "lastResponseId": "cri:2YOS8OR8jq2ov77Kx3US1vu5S6tk4VR"
    }
}

GET https://api.$(network)/v1/payments/instruction/cri:2YOS8OR9F...

Response

{
    "@type": "https://miapago.io/paymentinstruction/v0.1.0#PaymentInstruction",
    "originatorId": "PaylinkInitiator",
    "initiatorId": "PaylinkInitiator",
    "activatorId": "PaylinkInstructionRouter-activator",
    "activatingEntityId": "cri:2YOS8OR9FwmVYID3ux7eOKhbPy6ZpFn",
    "state": {
        "@type": "https://miapago.io/paymentinstruction#State",
        "activationState": "Activated:Processed:NonePending",
        "initiationTime": "2022-06-21T09:26:42.7090937Z",
        "id": "cri:2YOS8OR9FwmVYID3ux7eOKhbPy6ZpFn",
        "lastUpdateTime": "2022-06-21T09:26:43.2311355Z",
        "parties": {
            "payment:Payee": "cri:1lbmIdiG2dmZGQsJ23fpATis0wsN",
            "payment:Subscriber": "cri:1lbmIdiG2dmZGQsJ23fpATis0wsN"
        },
        "paymentState": {
            "@type": "https://miapago.io/ob/domesticpayment#State",
            "consent": "accept",
            "payeeName": "",
            "authorizationURL": "https://democonsentapp.netlify.app/democonsentapp?arg=?code=accept&state=7meca18qbvgSZ5fMLZqHQIM3",
            "paymentConsent": "test",
            "paymentStatus": ""
        },
        "instructed": {
            "value": "1",
            "unit": "ISO4217a:GBP"
        },
        "processed": {
            "value": "1",
            "unit": "ISO4217a:GBP"
        },
        "remaining": {
            "value": "0",
            "unit": "ISO4217a:GBP"
        }
    },
    "properties": {
        "@type": "https://miapago.io/paymentinstruction#Properties",
        "parties": {
            "payment:Payer": "cri:NTgRQ2DIfWWuQIlromAFnR"
        },
        "amount": {
            "value": "100",
            "unit": "ISO4217a:GBP"
        },
        "paymentMethod": {
            "methodType": "BoppPaylink",
            "properties": {
                "@type": "https://miapago.io/paylink#Properties",
                "paylink": "paylink://bopp.link/5x5g3",
                "linkedMethod": {
                    "methodType": "OpenBankingDomesticPayment",
                    "properties": {
                        "@type": "https://miapago.io/ob/domesticpayment#Properties",
                        "payeeServiceId": "",
                        "serviceId": "demo-aspsp",
                        "endToEndIdentification": "TestTransaction",
                        "name": "No Name",
                        "paymentReference": "BOPP payment"
                    }
                }
            }
        },
        "idToken": "eyJhbGciOiJQUzI1NiIsImtpZCI6ImlMUEhFZ09pRzhaY1ZQdU9QenVTY2hkUDR3cyIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FwaS5tb256by5jb20vb3Blbi1iYW5raW5nLyIsImF1ZCI6Im9hdXRoMmNsaWVudF8wMDAwOXZDTXpud0J3MnZQcEdOTld6IiwiZXhwIjoxNjA1Njk3MjI0LCJpYXQiOjE2MDU2MTA4MjQsIm5iZiI6MTYwNTYxMDgyNCwic3ViIjoib2JwaXNwZG9tZXN0aWNwYXltZW50Y29uc2VudF8wMDAwQTFIcjg3UUZjYjRCYjl1aVVUIiwiYXV0aF90aW1lIjoxNjA1NjEwODI0LCJub25jZSI6IjEwYTQ5MmNkLTczOWMtNDY0Yi05YjA3LTkyZWRmMDQyMzJkMyIsIm9wZW5iYW5raW5nX2ludGVudF9pZCI6Im9icGlzcGRvbWVzdGljcGF5bWVudGNvbnNlbnRfMDAwMEExSHI4N1FGY2I0QmI5dWlVVCIsImFjciI6InVybjpvcGVuYmFua2luZzpwc2QyOnNjYSIsInNfaGFzaCI6IlRlQTVlSFBzdnEta2xSa0tMV3ZRQWciLCJjX2hhc2giOiJYVjBmSnM0OHlGWS1QODFFQjhnX25BIn0.RL9j5fg0R39KzDm3703jt-gAwd1JCpgzpvRXhgyawWGxwjwkonFnKlYYspkqxCCtKXdWjHovNjfzif8NcVeG4gnhC-hBmqemWqdRK-w2tG_uAh4IVBiZdM8m2El2Sg5VADECRC-0E291jnZnDo7wr-qV7f2wMSu4orpJpHssh997Tfostm7FlDqJSw-NeOhpKmn8qZ9N5jmmKL20GX-mcgljKtIxTYmu2sGWjHVIe9q0jWQgbBPN5__6Kp-0F2KLJQeAfG4slfnkuxwTdwePvIdt08o2_GoPyb3-qgYAcviepPOJf6Zp06yhk2FhDmlLwCwZr8SqWSy_xLU-vFrJTg"
    },
    "requestContext": {
        "lastAcceptedRequestId": "cri:7mbLBCC1SPJGiFdUpyLlnod8",
        "lastRequestId": "cri:7mbLBCC1SPJGiFdUpyLlnod8",
        "lastResponseId": "cri:2YOS8OR8jsouMAHQS65kd7Gqen4CnY2"
    }
}