# removed refs to `optional-signature` and `optional-signature-input` (in `signature` and `signature-input`) and inline instead
# to fix error on `oapi-codegen -generate types ...`
openapi: 3.1.0
info:
title: Open Payments
version: "1.4"
license:
name: Apache 2.0
identifier: Apache-2.0
description: |-
The Open Payments API is a simple REST API with 4 resource types: **wallet address**, **quote**, **incoming payment** and **outgoing payment**.
The *service endpoint* for the API is always the URL of the wallet address resource and all other resources are sub-resources of the wallet address.
An incoming payment defines meta data that is automatically attached to payments made into the wallet address under that incoming payment. This facilitates automation of processes like reconciliation of payment into the wallet address with external systems.
An outgoing payment is an instruction to make a payment out of the wallet address.
A quote is a commitment from the Account Servicing Entity to deliver a particular amount to a receiver when sending a particular amount from the wallet address. It is only valid for a limited time.
All resource and collection resource representations use JSON and the media-type `application/json`.
The `wallet address` resource has three collections of sub-resources:
1. `/incoming-payments` contains the **incoming payment** sub-resources
2. `/outgoing-payments` contains the **outgoing payment** sub-resources
3. `/quotes` contains the **quote** sub-resources
Access to resources and permission to execute the methods exposed by the API is determined by the grants given to the client represented by an access token used in API requests.
summary: An API for open access to financial accounts to send and receive payments.
contact:
email: tech@interledger.org
servers:
- url: "https://ilp.rafiki.money"
description: "Server for wallet address subresources (ie https://ilp.rafiki.money/alice)"
- url: "https://ilp.rafiki.money/.well-known/pay"
description: "Server for when the wallet address has no pathname (ie https://ilp.rafiki.money)"
tags:
- name: wallet-address
description: wallet address operations
- name: incoming-payment
description: incoming payment operations
- name: outgoing-payment
description: outgoing payment operations
- name: quote
description: quote operations
paths:
/incoming-payments:
post:
summary: Create an Incoming Payment
tags:
- incoming-payment
operationId: create-incoming-payment
responses:
"201":
description: Incoming Payment Created
content:
application/json:
schema:
$ref: "#/components/schemas/incoming-payment-with-methods"
examples:
New Incoming Payment for $25:
value:
id: "https://ilp.rafiki.money/incoming-payments/08394f02-7b7b-45e2-b645-51d04e7c330c"
walletAddress: "https://ilp.rafiki.money/alice/"
incomingAmount:
value: "2500"
assetCode: USD
assetScale: 2
receivedAmount:
value: "0"
assetCode: USD
assetScale: 2
completed: false
expiresAt: "2022-02-03T23:20:50.52Z"
metadata:
externalRef: INV2022-02-0137
createdAt: "2022-03-12T23:20:50.52Z"
updatedAt: "2022-04-01T10:24:36.11Z"
methods:
- type: ilp
ilpAddress: g.ilp.iwuyge987y.98y08y
sharedSecret: 1c7eaXa4rd2fFOBl1iydvCT1tV5TbM3RW1WLCafu_JA
"401":
$ref: "#/components/responses/401"
"403":
$ref: "#/components/responses/403"
requestBody:
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
walletAddress:
$ref: ./schemas.yaml#/components/schemas/walletAddress
incomingAmount:
$ref: ./schemas.yaml#/components/schemas/amount
description: The maximum amount that should be paid into the wallet address under this incoming payment.
expiresAt:
type: string
description: The date and time when payments into the incoming payment must no longer be accepted.
format: date-time
writeOnly: true
metadata:
type: object
description: Additional metadata associated with the incoming payment. (Optional)
required:
- walletAddress
examples:
Create incoming payment for $25 to pay invoice INV2022-02-0137:
value:
walletAddress: "https://openpayments.guide/alice/"
incomingAmount:
value: "2500"
assetCode: USD
assetScale: 2
metadata:
externalRef: INV2022-02-0137
description: |-
A subset of the incoming payments schema is accepted as input to create a new incoming payment.
The `incomingAmount` must use the same `assetCode` and `assetScale` as the wallet address.
required: true
description: |-
A client MUST create an **incoming payment** resource before it is possible to send any payments to the wallet address.
When a client creates an **incoming payment** the receiving Account Servicing Entity generates unique payment details that can be used to address payments to the account and returns these details to the client as properties of the new **incoming payment**. Any payments received using those details are then associated with the **incoming payment**.
All of the input parameters are _optional_.
For example, the client could use the `metadata` property to store an external reference on the **incoming payment** and this can be shared with the account holder to assist with reconciliation.
If `incomingAmount` is specified and the total received using the payment details equals or exceeds the specified `incomingAmount`, then the receiving Account Servicing Entity MUST reject any further payments and set `completed` to `true`.
If an `expiresAt` value is defined, and the current date and time on the receiving Account Servicing Entity's systems exceeds that value, the receiving Account Servicing Entity MUST reject any further payments.
parameters:
- $ref: "#/components/parameters/signature-input"
- $ref: "#/components/parameters/signature"
get:
summary: List Incoming Payments
operationId: list-incoming-payments
responses:
"200":
description: OK
content:
application/json:
schema:
type: object
properties:
pagination:
$ref: "#/components/schemas/page-info"
result:
type: array
items:
$ref: "#/components/schemas/incoming-payment"
additionalProperties: false
examples:
forward pagination:
value:
pagination:
startCursor: 241de237-f989-42be-926d-c0c1fca57708
endCursor: 315581f8-9967-45a0-9cd3-87b60b6d6414
hasPreviousPage: false
hasNextPage: true
result:
- id: "https://ilp.rafiki.money/incoming-payments/016da9d5-c9a4-4c80-a354-86b915a04ff8"
walletAddress: "https://ilp.rafiki.money/alice/"
incomingAmount:
value: "250"
assetCode: USD
assetScale: 2
receivedAmount:
value: "250"
assetCode: USD
assetScale: 2
metadata:
description: "Hi Mo, this is for the cappuccino I bought for you the other day."
externalRef: Coffee w/ Mo on 10 March 22
expiresAt: "2022-04-12T23:20:50.52Z"
createdAt: "2022-03-12T23:20:50.52Z"
updatedAt: "2022-04-01T10:24:36.11Z"
completed: true
- id: "https://ilp.rafiki.money/incoming-payments/32abc219-3dc3-44ec-a225-790cacfca8fa"
walletAddress: "https://ilp.rafiki.money/alice/"
receivedAmount:
value: "100"
assetCode: USD
assetScale: 2
expiresAt: "2022-04-12T23:20:50.52Z"
createdAt: "2022-03-12T23:20:50.52Z"
updatedAt: "2022-04-01T10:24:36.11Z"
metadata:
description: "I love your website, Alice! Thanks for the great content"
completed: false
backward pagination:
value:
pagination:
startCursor: 241de237-f989-42be-926d-c0c1fca57708
endCursor: 315581f8-9967-45a0-9cd3-87b60b6d6414
hasPreviousPage: true
hasNextPage: false
result:
- id: "https://ilp.rafiki.money/incoming-payments/32abc219-3dc3-44ec-a225-790cacfca8fa"
walletAddress: "https://ilp.rafiki.money/alice/"
receivedAmount:
value: "100"
assetCode: USD
assetScale: 2
completed: true
expiresAt: "2022-04-12T23:20:50.52Z"
createdAt: "2022-03-12T23:20:50.52Z"
updatedAt: "2022-04-01T10:24:36.11Z"
metadata:
description: "I love your website, Alice! Thanks for the great content"
- id: "https://ilp.rafiki.money/incoming-payments/016da9d5-c9a4-4c80-a354-86b915a04ff8"
walletAddress: "https://ilp.rafiki.money/alice/"
incomingAmount:
value: "250"
assetCode: USD
assetScale: 2
receivedAmount:
value: "250"
assetCode: USD
assetScale: 2
completed: true
expiresAt: "2022-04-12T23:20:50.52Z"
createdAt: "2022-03-12T23:20:50.52Z"
updatedAt: "2022-04-01T10:24:36.11Z"
metadata:
description: "Hi Mo, this is for the cappuccino I bought for you the other day."
externalRef: Coffee w/ Mo on 10 March 22
"401":
$ref: "#/components/responses/401"
"403":
$ref: "#/components/responses/403"
description: List all incoming payments on the wallet address
parameters:
- $ref: "#/components/parameters/wallet-address"
- $ref: "#/components/parameters/cursor"
- $ref: "#/components/parameters/first"
- $ref: "#/components/parameters/last"
- $ref: "#/components/parameters/signature-input"
- $ref: "#/components/parameters/signature"
tags:
- incoming-payment
/outgoing-payments:
post:
summary: Create an Outgoing Payment
tags:
- outgoing-payment
operationId: create-outgoing-payment
responses:
"201":
description: Outgoing Payment Created
content:
application/json:
schema:
$ref: "#/components/schemas/outgoing-payment"
examples:
New Fixed Send Outgoing Payment for $25:
value:
id: "https://ilp.rafiki.money/outgoing-payments/8c68d3cc-0a0f-4216-98b4-4fa44a6c88cf"
walletAddress: "https://ilp.rafiki.money/alice/"
failed: false
receiver: "https://ilp.rafiki.money/bob/incoming-payments/48884225-b393-4872-90de-1b737e2491c2"
debitAmount:
value: "2600"
assetCode: USD
assetScale: 2
receiveAmount:
value: "2500"
assetCode: USD
assetScale: 2
sentAmount:
value: "0"
assetCode: USD
assetScale: 2
metadata:
description: Thank you for the shoes.
createdAt: "2022-03-12T23:20:50.52Z"
updatedAt: "2022-04-01T10:24:36.11Z"
"401":
$ref: "#/components/responses/401"
"403":
$ref: "#/components/responses/403"
requestBody:
content:
application/json:
examples:
Create an outgoing payment based on a quote:
value:
walletAddress: "https://ilp.rafiki.money/alice/"
quoteId: "https://ilp.rafiki.money/quotes/ab03296b-0c8b-4776-b94e-7ee27d868d4d"
metadata:
externalRef: INV2022-02-0137
schema:
type: object
properties:
walletAddress:
$ref: ./schemas.yaml#/components/schemas/walletAddress
quoteId:
type: string
format: uri
description: The URL of the quote defining this payment's amounts.
metadata:
type: object
additionalProperties: true
description: Additional metadata associated with the outgoing payment. (Optional)
required:
- quoteId
- walletAddress
additionalProperties: false
description: |-
A subset of the outgoing payments schema is accepted as input to create a new outgoing payment.
The `debitAmount` must use the same `assetCode` and `assetScale` as the wallet address.
required: true
description: |-
An **outgoing payment** is a sub-resource of a wallet address. It represents a payment from the wallet address.
Once created, it is already authorized and SHOULD be processed immediately. If payment fails, the Account Servicing Entity must mark the **outgoing payment** as `failed`.
parameters:
- $ref: "#/components/parameters/signature-input"
- $ref: "#/components/parameters/signature"
description: Create a new outgoing payment at the wallet address.
get:
summary: List Outgoing Payments
operationId: list-outgoing-payments
responses:
"200":
description: OK
content:
application/json:
schema:
type: object
properties:
pagination:
$ref: "#/components/schemas/page-info"
result:
type: array
items:
$ref: "#/components/schemas/outgoing-payment"
examples:
forward pagination:
value:
pagination:
startCursor: 241de237-f989-42be-926d-c0c1fca57708
endCursor: 315581f8-9967-45a0-9cd3-87b60b6d6414
hasPreviousPage: false
hasNextPage: true
result:
- id: "https://ilp.rafiki.money/outgoing-payments/8c68d3cc-0a0f-4216-98b4-4fa44a6c88cf"
walletAddress: "https://ilp.rafiki.money/alice/"
failed: false
receiver: "https://ilp.rafiki.money/aplusvideo/incoming-payments/45d495ad-b763-4882-88d7-aa14d261686e"
receiveAmount:
value: "2500"
assetCode: USD
assetScale: 2
debitAmount:
value: "2600"
assetCode: USD
assetScale: 2
sentAmount:
value: "2500"
assetCode: USD
assetScale: 2
createdAt: "2022-03-12T23:20:50.52Z"
updatedAt: "2022-04-01T10:24:36.11Z"
metadata:
description: APlusVideo subscription
externalRef: "customer: 847458475"
- id: "https://ilp.rafiki.money/outgoing-payments/0cffa5a4-58fd-4cc8-8e01-7145c72bf07c"
walletAddress: "https://ilp.rafiki.money/alice/"
failed: false
receiver: "https://ilp.rafiki.money/shoeshop/incoming-payments/2fe92c6f-ef0d-487c-8759-3784eae6bce9"
debitAmount:
value: "7126"
assetCode: USD
assetScale: 2
receiveAmount:
value: "7026"
assetCode: USD
assetScale: 2
sentAmount:
value: "7026"
assetCode: USD
assetScale: 2
createdAt: "2022-03-12T23:20:50.52Z"
updatedAt: "2022-04-01T10:24:36.11Z"
metadata:
description: Thank you for your purchase at ShoeShop!
externalRef: INV2022-8943756
backward pagination:
value:
pagination:
startCursor: 241de237-f989-42be-926d-c0c1fca57708
endCursor: 315581f8-9967-45a0-9cd3-87b60b6d6414
hasPreviousPage: true
hasNextPage: false
result:
- id: "https://ilp.rafiki.money/outgoing-payments/0cffa5a4-58fd-4cc8-8e01-7145c72bf07c"
walletAddress: "https://ilp.rafiki.money/alice/"
failed: false
receiver: "https://ilp.rafiki.money/shoeshop/incoming-payments/2fe92c6f-ef0d-487c-8759-3784eae6bce9"
debitAmount:
value: "7126"
assetCode: USD
assetScale: 2
receiveAmount:
value: "7026"
assetCode: USD
assetScale: 2
sentAmount:
value: "7026"
assetCode: USD
assetScale: 2
createdAt: "2022-03-12T23:20:50.52Z"
updatedAt: "2022-04-01T10:24:36.11Z"
metadata:
description: Thank you for your purchase at ShoeShop!
externalRef: INV2022-8943756
- id: "https://ilp.rafiki.money/outgoing-payments/8c68d3cc-0a0f-4216-98b4-4fa44a6c88cf"
walletAddress: "https://ilp.rafiki.money/alice/"
failed: false
receiver: "https://ilp.rafiki.money/aplusvideo/incoming-payments/45d495ad-b763-4882-88d7-aa14d261686e"
receiveAmount:
value: "2500"
assetCode: USD
assetScale: 2
debitAmount:
value: "2600"
assetCode: USD
assetScale: 2
sentAmount:
value: "2500"
assetCode: USD
assetScale: 2
createdAt: "2022-03-12T23:20:50.52Z"
updatedAt: "2022-04-01T10:24:36.11Z"
metadata:
description: APlusVideo subscription
externalRef: "customer: 847458475"
"401":
$ref: "#/components/responses/401"
"403":
$ref: "#/components/responses/403"
description: List all outgoing payments on the wallet address
parameters:
- $ref: "#/components/parameters/wallet-address"
- $ref: "#/components/parameters/cursor"
- $ref: "#/components/parameters/first"
- $ref: "#/components/parameters/last"
- $ref: "#/components/parameters/signature-input"
- $ref: "#/components/parameters/signature"
tags:
- outgoing-payment
/quotes:
post:
summary: Create a Quote
tags:
- quote
operationId: create-quote
responses:
"201":
description: Quote Created
content:
application/json:
schema:
$ref: "#/components/schemas/quote"
examples:
New Fixed Send Quote for $25:
value:
id: "https://ilp.rafiki.money/quotes/8c68d3cc-0a0f-4216-98b4-4fa44a6c88cf"
walletAddress: "https://ilp.rafiki.money/alice/"
receiver: "https://ilp.rafiki.money/aplusvideo/incoming-payments/45d495ad-b763-4882-88d7-aa14d261686e"
debitAmount:
value: "2500"
assetCode: USD
assetScale: 2
receiveAmount:
value: "2198"
assetCode: EUR
assetScale: 2
method: ilp
createdAt: "2022-03-12T23:20:50.52Z"
expiresAt: "2022-04-12T23:20:50.52Z"
"400":
description: No amount was provided and no amount could be inferred from the receiver.
"401":
$ref: "#/components/responses/401"
"403":
$ref: "#/components/responses/403"
requestBody:
content:
application/json:
examples:
Create quote for an `receiver` that is an Incoming Payment with an `incomingAmount`:
value:
walletAddress: "https://ilp.rafiki.money/alice"
receiver: "https://ilp.rafiki.money/incoming-payments/37a0d0ee-26dc-4c66-89e0-01fbf93156f7"
method: ilp
Create fixed-send amount quote for $25:
value:
walletAddress: "https://ilp.rafiki.money/alice"
receiver: "https://ilp.rafiki.money/incoming-payments/37a0d0ee-26dc-4c66-89e0-01fbf93156f7"
method: ilp
debitAmount:
value: "2500"
assetCode: USD
assetScale: 2
Create fixed-receive amount quote for $25:
value:
walletAddress: "https://ilp.rafiki.money/alice"
receiver: "https://ilp.rafiki.money/incoming-payments/37a0d0ee-26dc-4c66-89e0-01fbf93156f7"
method: ilp
receiveAmount:
value: "2500"
assetCode: USD
assetScale: 2
schema:
oneOf:
- description: Create quote for an `receiver` that is an Incoming Payment with an `incomingAmount`
properties:
walletAddress:
$ref: ./schemas.yaml#/components/schemas/walletAddress
receiver:
$ref: ./schemas.yaml#/components/schemas/receiver
method:
$ref: "#/components/schemas/payment-method"
required:
- walletAddress
- receiver
- method
additionalProperties: false
- description: Create a quote with a fixed-receive amount
properties:
walletAddress:
$ref: ./schemas.yaml#/components/schemas/walletAddress
receiver:
$ref: ./schemas.yaml#/components/schemas/receiver
method:
$ref: "#/components/schemas/payment-method"
receiveAmount:
description: The fixed amount that would be paid into the receiving wallet address given a successful outgoing payment.
$ref: ./schemas.yaml#/components/schemas/amount
required:
- walletAddress
- receiver
- method
- receiveAmount
additionalProperties: false
- description: Create a quote with a fixed-send amount
properties:
walletAddress:
$ref: ./schemas.yaml#/components/schemas/walletAddress
receiver:
$ref: ./schemas.yaml#/components/schemas/receiver
method:
$ref: "#/components/schemas/payment-method"
debitAmount:
description: The fixed amount that would be sent from the sending wallet address given a successful outgoing payment.
$ref: ./schemas.yaml#/components/schemas/amount
required:
- walletAddress
- receiver
- method
- debitAmount
additionalProperties: false
description: |-
A subset of the quotes schema is accepted as input to create a new quote.
The quote must be created with a (`debitAmount` xor `receiveAmount`) unless the `receiver` is an Incoming Payment which has an `incomingAmount`.
required: true
description: A **quote** is a sub-resource of a wallet address. It represents a quote for a payment from the wallet address.
parameters:
- $ref: "#/components/parameters/signature-input"
- $ref: "#/components/parameters/signature"
description: Create a new quote at the wallet address.
"/incoming-payments/{id}":
get:
summary: Get an Incoming Payment
tags:
- incoming-payment
operationId: get-incoming-payment
responses:
"200":
description: Incoming Payment Found
content:
application/json:
schema:
anyOf:
- $ref: "#/components/schemas/incoming-payment-with-methods"
- $ref: "#/components/schemas/public-incoming-payment"
examples:
Incoming Payment for $25 with $12.34 received so far:
value:
id: "https://ilp.rafiki.money/incoming-payments/2f1b0150-db73-49e8-8713-628baa4a17ff"
walletAddress: "https://ilp.rafiki.money/alice/"
incomingAmount:
value: "2500"
assetCode: USD
assetScale: 2
receivedAmount:
value: "1234"
assetCode: USD
assetScale: 2
completed: false
expiresAt: "2022-04-12T23:20:50.52Z"
createdAt: "2022-03-12T23:20:50.52Z"
updatedAt: "2022-04-01T10:24:36.11Z"
metadata:
description: Thanks for the flowers!
externalRef: INV-12876
methods:
- type: ilp
ilpAddress: g.ilp.iwuyge987y.98y08y
sharedSecret: 1c7eaXa4rd2fFOBl1iydvCT1tV5TbM3RW1WLCafu_JA
"401":
$ref: "#/components/responses/401"
"403":
$ref: "#/components/responses/403"
"404":
description: Incoming Payment Not Found
parameters:
- $ref: "#/components/parameters/optional-signature-input"
- $ref: "#/components/parameters/optional-signature"
description: A client can fetch the latest state of an incoming payment to determine the amount received into the wallet address.
parameters:
- $ref: "#/components/parameters/id"
"/incoming-payments/{id}/complete":
post:
summary: Complete an Incoming Payment
tags:
- incoming-payment
operationId: complete-incoming-payment
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/incoming-payment"
additionalProperties: false
examples:
Completed Incoming Payment:
value:
id: "https://ilp.rafiki.money/incoming-payments/016da9d5-c9a4-4c80-a354-86b915a04ff8"
walletAddress: "https://ilp.rafiki.money/alice/"
incomingAmount:
value: "250"
assetCode: USD
assetScale: 2
receivedAmount:
value: "250"
assetCode: USD
assetScale: 2
completed: true
expiresAt: "2022-04-12T23:20:50.52Z"
createdAt: "2022-03-12T23:20:50.52Z"
updatedAt: "2022-04-01T10:24:36.11Z"
metadata:
description: "Hi Mo, this is for the cappuccino I bought for you the other day."
externalRef: Coffee w/ Mo on 10 March 2
"401":
$ref: "#/components/responses/401"
"403":
$ref: "#/components/responses/403"
"404":
description: Incoming Payment Not Found
description: |-
A client with the appropriate permissions MAY mark a non-expired **incoming payment** as `completed` indicating that the client is not going to make any further payments toward this **incoming payment**, even though the full `incomingAmount` may not have been received.
This indicates to the receiving Account Servicing Entity that it can begin any post processing of the payment such as generating account statements or notifying the account holder of the completed payment.
parameters:
- $ref: "#/components/parameters/signature-input"
- $ref: "#/components/parameters/signature"
parameters:
- $ref: "#/components/parameters/id"
"/outgoing-payments/{id}":
get:
summary: Get an Outgoing Payment
tags:
- outgoing-payment
operationId: get-outgoing-payment
responses:
"200":
description: Outgoing Payment Found
content:
application/json:
schema:
$ref: "#/components/schemas/outgoing-payment"
examples:
Outgoing Payment with a fixed send amount of $25:
value:
id: "https://ilp.rafiki.money/bob/outgoing-payments/3859b39e-4666-4ce5-8745-72f1864c5371"
walletAddress: "https://ilp.rafiki.money/bob/"
failed: false
receiver: "https://ilp.rafiki.money/incoming-payments/2f1b0150-db73-49e8-8713-628baa4a17ff"
debitAmount:
value: "2500"
assetCode: USD
assetScale: 2
receiveAmount:
value: "2198"
assetCode: EUR
assetScale: 2
sentAmount:
value: "1205"
assetCode: USD
assetScale: 2
createdAt: "2022-03-12T23:20:50.52Z"
updatedAt: "2022-04-01T10:24:36.11Z"
metadata:
description: Thanks for the flowers!
externalRef: INV-12876
"401":
$ref: "#/components/responses/401"
"403":
$ref: "#/components/responses/403"
"404":
description: Outgoing Payment Not Found
description: A client can fetch the latest state of an outgoing payment.
parameters:
- $ref: "#/components/parameters/signature-input"
- $ref: "#/components/parameters/signature"
parameters:
- $ref: "#/components/parameters/id"
"/quotes/{id}":
get:
summary: Get a Quote
tags:
- quote
operationId: get-quote
responses:
"200":
description: Quote Found
content:
application/json:
schema:
$ref: "#/components/schemas/quote"
examples:
Quote with a fixed send amount of $25:
value:
id: "https://ilp.rafiki.money/bob/quotes/3859b39e-4666-4ce5-8745-72f1864c5371"
walletAddress: "https://ilp.rafiki.money/bob/"
receiver: "https://ilp.rafiki.money/incoming-payments/2f1b0150-db73-49e8-8713-628baa4a17ff"
debitAmount:
value: "2500"
assetCode: USD
assetScale: 2
receiveAmount:
value: "2198"
assetCode: EUR
assetScale: 2
method: ilp
createdAt: "2022-03-12T23:20:50.52Z"
expiresAt: "2022-04-12T23:20:50.52Z"
"401":
$ref: "#/components/responses/401"
"403":
$ref: "#/components/responses/403"
"404":
description: Quote Not Found
description: A client can fetch the latest state of a quote.
parameters:
- $ref: "#/components/parameters/signature-input"
- $ref: "#/components/parameters/signature"
parameters:
- $ref: "#/components/parameters/id"
components:
schemas:
incoming-payment:
title: Incoming Payment
description: "An **incoming payment** resource represents a payment that will be, is currently being, or has been received by the account."
type: object
examples:
- id: "https://ilp.rafiki.money/incoming-payments/016da9d5-c9a4-4c80-a354-86b915a04ff8"
walletAddress: "https://ilp.rafiki.money/alice/"
incomingAmount:
value: "250"
assetCode: USD
assetScale: 2
receivedAmount:
value: "250"
assetCode: USD
assetScale: 2
completed: true
expiresAt: "2022-04-12T23:20:50.52Z"
createdAt: "2022-03-12T23:20:50.52Z"
updatedAt: "2022-04-01T10:24:36.11Z"
metadata:
description: "Hi Mo, this is for the cappuccino I bought for you the other day."
externalRef: Coffee w/ Mo on 10 March 22
- id: "https://ilp.rafiki.money/incoming-payments/456da9d5-c9a4-4c80-a354-86b915a04ff8"
walletAddress: "https://ilp.rafiki.money/alice/"
incomingAmount:
value: "2500"
assetCode: USD
assetScale: 2
receivedAmount:
value: "0"
assetCode: USD
assetScale: 2
expiresAt: "2022-04-12T23:20:50.52Z"
createdAt: "2022-03-12T23:20:50.52Z"
updatedAt: "2022-03-12T23:20:50.52Z"
properties:
id:
type: string
format: uri
description: The URL identifying the incoming payment.
readOnly: true
walletAddress:
type: string
format: uri
description: The URL of the wallet address this payment is being made into.
readOnly: true
completed:
type: boolean
description: Describes whether the incoming payment has completed receiving fund.
default: false
incomingAmount:
$ref: ./schemas.yaml#/components/schemas/amount
description: The maximum amount that should be paid into the wallet address under this incoming payment.
receivedAmount:
$ref: ./schemas.yaml#/components/schemas/amount
description: The total amount that has been paid into the wallet address under this incoming payment.
expiresAt:
type: string
description: The date and time when payments under this incoming payment will no longer be accepted.
format: date-time
metadata:
type: object
description: Additional metadata associated with the incoming payment. (Optional)
createdAt:
type: string
format: date-time
description: The date and time when the incoming payment was created.
updatedAt:
type: string
format: date-time
description: The date and time when the incoming payment was updated.
required:
- id
- walletAddress
- completed
- receivedAmount
- createdAt
- updatedAt
incoming-payment-with-methods:
title: Incoming Payment with payment methods
description: An **incoming payment** resource with public details.
allOf:
- $ref: "#/components/schemas/incoming-payment"
- type: object
properties:
methods:
description: The list of payment methods supported by this incoming payment.
type: array
uniqueItems: true
minItems: 0
items:
anyOf:
- $ref: "#/components/schemas/ilp-payment-method"
required:
- methods
public-incoming-payment:
title: Public Incoming Payment
description: An **incoming payment** resource with public details.
type: object
examples:
- receivedAmount:
value: "0"
assetCode: USD
assetScale: 2
- authServer: "https://auth.rafiki.money"
properties:
receivedAmount:
$ref: ./schemas.yaml#/components/schemas/amount
authServer:
type: string
format: uri
description: The URL of the authorization server endpoint for getting grants and access tokens for this wallet address.
required:
- authServer
unresolvedProperites: false
outgoing-payment:
title: Outgoing Payment
description: "An **outgoing payment** resource represents a payment that will be, is currently being, or has previously been, sent from the wallet address."
type: object
examples:
- id: "https://ilp.rafiki.money/outgoing-payments/8c68d3cc-0a0f-4216-98b4-4fa44a6c88cf"
walletAddress: "https://ilp.rafiki.money/alice/"
failed: false
receiver: "https://ilp.rafiki.money/aplusvideo/incoming-payments/45d495ad-b763-4882-88d7-aa14d261686e"
receiveAmount:
value: "2500"
assetCode: USD
assetScale: 2
debitAmount:
value: "2600"
assetCode: USD
assetScale: 2
sentAmount:
value: "2500"
assetCode: USD
assetScale: 2
createdAt: "2022-03-12T23:20:50.52Z"
updatedAt: "2022-04-01T10:24:36.11Z"
metadata:
description: APlusVideo subscription
externalRef: "customer: 847458475"
- id: "https://ilp.rafiki.money/outgoing-payments/0cffa5a4-58fd-4cc8-8e01-7145c72bf07c"
walletAddress: "https://ilp.rafiki.money/alice/"
failed: false
receiver: "https://ilp.rafiki.money/shoeshop/2fe92c6f-ef0d-487c-8759-3784eae6bce9"
debitAmount:
value: "7126"
assetCode: USD
assetScale: 2
sentAmount:
value: "7026"
assetCode: USD
assetScale: 2
createdAt: "2022-03-12T23:20:50.52Z"
updatedAt: "2022-04-01T10:24:36.11Z"
metadata:
description: Thank you for your purchase at ShoeShop!
externalRef: INV2022-8943756
additionalProperties: false
properties:
id:
type: string
format: uri
description: The URL identifying the outgoing payment.
readOnly: true
walletAddress:
type: string
format: uri
description: The URL of the wallet address from which this payment is sent.
readOnly: true
quoteId:
type: string
format: uri
description: The URL of the quote defining this payment's amounts.
readOnly: true
failed:
type: boolean
description: Describes whether the payment failed to send its full amount.
default: false
receiver:
$ref: ./schemas.yaml#/components/schemas/receiver
description: The URL of the incoming payment that is being paid.
receiveAmount:
$ref: ./schemas.yaml#/components/schemas/amount
description: The total amount that should be received by the receiver when this outgoing payment has been paid.
debitAmount:
$ref: ./schemas.yaml#/components/schemas/amount
description: The total amount that should be deducted from the sender's account when this outgoing payment has been paid.
sentAmount:
$ref: ./schemas.yaml#/components/schemas/amount
description: The total amount that has been sent under this outgoing payment.
metadata:
type: object
description: Additional metadata associated with the outgoing payment. (Optional)
createdAt:
type: string
format: date-time
description: The date and time when the outgoing payment was created.
updatedAt:
type: string
format: date-time
description: The date and time when the outgoing payment was updated.
required:
- id
- walletAddress
- receiver
- receiveAmount
- debitAmount
- sentAmount
- createdAt
- updatedAt
quote:
title: Quote
description: A **quote** resource represents the quoted amount details with which an Outgoing Payment may be created.
type: object
examples:
- id: "https://ilp.rafiki.money/quotes/ab03296b-0c8b-4776-b94e-7ee27d868d4d"
walletAddress: "https://ilp.rafiki.money/alice/"
receiver: "https://ilp.rafiki.money/shoeshop/incoming-payments/2fe92c6f-ef0d-487c-8759-3784eae6bce9"
receiveAmount:
value: "2500"
assetCode: USD
assetScale: 2
debitAmount:
value: "2600"
assetCode: USD
assetScale: 2
sentAmount:
value: "2500"
assetCode: USD
assetScale: 2
method: ilp
createdAt: "2022-03-12T23:20:50.52Z"
expiresAt: "2022-04-12T23:20:50.52Z"
- id: "https://ilp.rafiki.money/quotes/8c68d3cc-0a0f-4216-98b4-4fa44a6c88cf"
walletAddress: "https://ilp.rafiki.money/alice/"
receiver: "https://ilp.rafiki.money/aplusvideo/incoming-payments/45d495ad-b763-4882-88d7-aa14d261686e"
debitAmount:
value: "7126"
assetCode: USD
assetScale: 2
sentAmount:
value: "7026"
assetCode: USD
assetScale: 2
method: ilp
createdAt: "2022-03-12T23:20:50.52Z"
expiresAt: "2022-04-12T23:20:50.52Z"
additionalProperties: false
properties:
id:
type: string
format: uri
description: The URL identifying the quote.
readOnly: true
walletAddress:
type: string
format: uri
description: The URL of the wallet address from which this quote's payment would be sent.
readOnly: true
receiver:
$ref: ./schemas.yaml#/components/schemas/receiver
description: The URL of the incoming payment that the quote is created for.
receiveAmount:
$ref: ./schemas.yaml#/components/schemas/amount
description: The total amount that should be received by the receiver when the corresponding outgoing payment has been paid.
debitAmount:
$ref: ./schemas.yaml#/components/schemas/amount
description: "The total amount that should be deducted from the sender's account when the corresponding outgoing payment has been paid. "
method:
$ref: "#/components/schemas/payment-method"
expiresAt:
type: string
description: The date and time when the calculated `debitAmount` is no longer valid.
readOnly: true
createdAt:
type: string
format: date-time
description: The date and time when the quote was created.
required:
- id
- walletAddress
- receiver
- receiveAmount
- debitAmount
- createdAt
- method
page-info:
description: ""
type: object
examples:
- startCursor: 241de237-f989-42be-926d-c0c1fca57708
endCursor: 315581f8-9967-45a0-9cd3-87b60b6d6414
hasNextPage: true
hasPreviousPage: true
properties:
startCursor:
type: string
minLength: 1
description: Cursor corresponding to the first element in the result array.
endCursor:
type: string
minLength: 1
description: Cursor corresponding to the last element in the result array.
hasNextPage:
type: boolean
description: Describes whether the data set has further entries.
hasPreviousPage:
type: boolean
description: Describes whether the data set has previous entries.
required:
- hasNextPage
- hasPreviousPage
additionalProperties: false
payment-method:
type: string
enum:
- ilp
ilp-payment-method:
type: object
additionalProperties: false
properties:
type:
type: string
enum:
- ilp
ilpAddress:
type: string
maxLength: 1023
pattern: "^(g|private|example|peer|self|test[1-3]?|local)([.][a-zA-Z0-9_~-]+)+$"
description: The ILP address to use when establishing a STREAM connection.
sharedSecret:
type: string
pattern: "^[a-zA-Z0-9-_]+$"
description: The base64 url-encoded shared secret to use when establishing a STREAM connection.
required:
- type
- ilpAddress
- sharedSecret
examples:
- type: string
ilpAddress: string
sharedSecret: string
securitySchemes:
GNAP:
name: Authorization
type: apiKey
in: header
description: |-
The API uses the Grant Negotiation and Authorization Protocol for authorization. An access token must be acquired from an authorization server before accessing the API and then provided in the request headers using the prefix `GNAP`.
All requests must also be signed using a client key over some select headers and a digest of the request body.
responses:
"401":
description: Authorization required
headers:
WWW-Authenticate:
schema:
type: string
description: The address of the authorization server for grant requests in the format `GNAP as_uri=<URI>`
"403":
description: Forbidden
parameters:
cursor:
schema:
type: string
minLength: 1
name: cursor
in: query
description: The cursor key to list from.
first:
schema:
type: integer
minimum: 1
maximum: 100
name: first
in: query
description: The number of items to return after the cursor.
last:
schema:
type: integer
minimum: 1
maximum: 100
name: last
in: query
description: The number of items to return before the cursor.
id:
name: id
in: path
schema:
type: string
description: Sub-resource identifier
required: true
wallet-address:
name: wallet-address
in: query
schema:
type: string
description: "URL of a wallet address hosted by a Rafiki instance."
required: true
signature:
name: Signature
in: header
schema:
type: string
example: "Signature: sig1=:EWJgAONk3D6542Scj8g51rYeMHw96cH2XiCMxcyL511wyemGcw==:"
description: 'The signature generated based on the Signature-Input, using the signing algorithm specified in the "alg" field of the JWK.'
required: true
signature-input:
name: Signature-Input
in: header
schema:
type: string
example: 'Signature-Input: sig1=("@method" "@target-uri" "content-digest" "content-length" "content-type");created=1618884473;keyid="gnap-rsa"'
description: 'The Signature-Input field is a Dictionary structured field containing the metadata for one or more message signatures generated from components within the HTTP message. Each member describes a single message signature. The member''s key is the label that uniquely identifies the message signature within the context of the HTTP message. The member''s value is the serialization of the covered components Inner List plus all signature metadata parameters identified by the label. The following components MUST be included: - "@method" - "@target-uri" - "authorization". When the message contains a request body, the covered components MUST also include the following: - "content-digest" The keyid parameter of the signature MUST be set to the kid value of the JWK. See [ietf-httpbis-message-signatures](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-message-signatures#section-4.1) for more details.'
required: true
optional-signature:
name: Signature
in: header
schema:
type: string
example: "Signature: sig1=:EWJgAONk3D6542Scj8g51rYeMHw96cH2XiCMxcyL511wyemGcw==:"
description: 'The signature generated based on the Signature-Input, using the signing algorithm specified in the "alg" field of the JWK.'
optional-signature-input:
name: Signature-Input
in: header
schema:
type: string
example: 'Signature-Input: sig1=("@method" "@target-uri" "content-digest" "content-length" "content-type");created=1618884473;keyid="gnap-rsa"'
description: 'The Signature-Input field is a Dictionary structured field containing the metadata for one or more message signatures generated from components within the HTTP message. Each member describes a single message signature. The member''s key is the label that uniquely identifies the message signature within the context of the HTTP message. The member''s value is the serialization of the covered components Inner List plus all signature metadata parameters identified by the label. The following components MUST be included: - "@method" - "@target-uri" - "authorization". When the message contains a request body, the covered components MUST also include the following: - "content-digest" The keyid parameter of the signature MUST be set to the kid value of the JWK. See [ietf-httpbis-message-signatures](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-message-signatures#section-4.1) for more details.'
security:
- GNAP: []