diff --git a/specs/2024-10-30.yaml b/specs/2024-10-30.yaml index 096be9e..bf709ae 100644 --- a/specs/2024-10-30.yaml +++ b/specs/2024-10-30.yaml @@ -823,41 +823,6 @@ paths: $ref: "#/components/responses/ForbiddenError" "500": $ref: "#/components/responses/InternalServerError" - /addresses/{id}: - get: - summary: Get Address - description: | - Retrieve an address with the given ID. - operationId: getAddress - tags: - - Addresses - security: - - bearerAuth: [] - parameters: - - name: id - in: path - description: The unique identifier for the address - required: true - schema: - type: string - example: "addr_1LaXpKGUcADgqoEMl0Cx0Ygg" - responses: - "200": - description: The address was retrieved - content: - application/json: - schema: - $ref: "#/components/schemas/Address" - "400": - $ref: "#/components/responses/BadRequestError" - "401": - $ref: "#/components/responses/AuthenticationError" - "403": - $ref: "#/components/responses/ForbiddenError" - "404": - $ref: "#/components/responses/NotFoundError" - "500": - $ref: "#/components/responses/InternalServerError" /events: get: summary: List Events @@ -1101,7 +1066,7 @@ paths: purpose: type: string description: | - What the File will be used for. We may add additional possible values for this enum over time; + What the File will be used for. We may add additional possible values for this enum over time; your application should be able to handle such additions gracefully. grant_letter: A grant letter tax_document: A tax document @@ -1218,155 +1183,6 @@ paths: $ref: "#/components/responses/NotFoundError" "500": $ref: "#/components/responses/InternalServerError" - /transactions: - post: - summary: Create a transaction - description: | - This endpoint is used to send transactional data to a nonprofit organization for a payment that is sent outside of Chariot. - Open payment networks that depend on the Federal Reserve are often very limited in terms of the data that can be sent with a payment. - This endpoint allows you to send additional data to the organization that can be used to reconcile the payment. - operationId: createTransaction - tags: - - Transactions - security: - - bearerAuth: [] - parameters: - - name: Idempotency-Key - in: header - description: | - The unique identifier for the request. - This header is used to ensure idempotency for requests that may be retried. - required: false - schema: - type: string - requestBody: - description: The transaction to create - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/Transaction" - examples: - WithPaymentId: - summary: DAF grant created with payment_id - value: - organization_id: "org_01j8rs605a4gctmbm58d87mvsj" - amount: 25000 - payment_id: "pay_01j8rs605a4gctmbm58d87mvsj" - currency: "USD" - description: "Payment for Grant 12345" - donation: - donor_advised_fund_grant: - organization_name: "DAFpay Network" - fund_name: "The Miller Family Fund" - purpose: "Where needed most" - donors: - - name: Bob Miller - email: bob.miller@gmail.com - responses: - "201": - description: The transaction was created - headers: - Location: - $ref: "#/components/headers/Location" - content: - application/json: - schema: - $ref: "#/components/schemas/Transaction" - "400": - $ref: "#/components/responses/BadRequestError" - "401": - $ref: "#/components/responses/AuthenticationError" - "403": - $ref: "#/components/responses/ForbiddenError" - "409": - $ref: "#/components/responses/ConflictError" - "500": - $ref: "#/components/responses/InternalServerError" - get: - summary: List transactions - description: | - List transactions. - operationId: listTransactions - tags: - - Transactions - security: - - bearerAuth: [] - parameters: - - name: address_id - in: query - description: The unique identifier for the address - required: false - schema: - type: string - - name: organization_id - in: query - description: The unique identifier for the organization - required: false - schema: - type: string - - name: limit - in: query - description: Limit the size of the list that is returned. The default (and maximum) is 100 objects. - required: false - schema: - type: integer - format: int32 - - name: page_token - in: query - description: The page token to use for pagination. If not set, the first page of results will be returned. - required: false - schema: - type: string - responses: - "200": - description: The transactions were retrieved - content: - application/json: - schema: - $ref: "#/components/schemas/TransactionList" - "400": - $ref: "#/components/responses/BadRequestError" - "401": - $ref: "#/components/responses/AuthenticationError" - "403": - $ref: "#/components/responses/ForbiddenError" - "500": - $ref: "#/components/responses/InternalServerError" - /transactions/{id}: - get: - summary: Retrieve a transaction - description: | - Get a transaction by its unique identifier. - operationId: getTransaction - tags: - - Transactions - security: - - bearerAuth: [] - parameters: - - name: id - in: path - description: The unique identifier for the transaction - required: true - schema: - type: string - responses: - "200": - description: The transaction was retrieved - content: - application/json: - schema: - $ref: "#/components/schemas/Transaction" - "400": - $ref: "#/components/responses/BadRequestError" - "401": - $ref: "#/components/responses/AuthenticationError" - "403": - $ref: "#/components/responses/ForbiddenError" - "404": - $ref: "#/components/responses/NotFoundError" - "500": - $ref: "#/components/responses/InternalServerError" /payments: post: summary: Create a payment @@ -1378,12 +1194,7 @@ paths: security: - bearerAuth: [] requestBody: - description: The payment to create - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/Payment" + $ref: "#/components/requestBodies/CreatePaymentRequest" responses: "201": description: The payment was created @@ -1412,13 +1223,6 @@ paths: security: - bearerAuth: [] parameters: - - name: address_id - in: query - description: The unique identifier for the address - required: true - schema: - type: string - example: "addr_1LaXpKGUcADgqoEMl0Cx0Ygg" - name: organization_id in: query description: The unique identifier for the organization @@ -1657,7 +1461,7 @@ components: type: string description: |- The name of the organization. - For organizations that operate under a different name than the one tied to the legal entity, + For organizations that operate under a different name than the one tied to the legal entity, this name will differ from the name of the linked entity. This is also known as the "DBA" or "Doing Business As" name of the organization. example: American Red Cross @@ -2159,16 +1963,10 @@ components: * postal: a mailing address * bank: a bank account number and routing number required: - - id - organization_id - type - supported_payment_methods properties: - id: - type: string - readOnly: true - description: The unique identifier for the object. - example: addr_1LaXpKGUcADgqoEMl0Cx0Ygg organization_id: type: string description: The unique identifier for the organization that this address is associated with. @@ -2190,18 +1988,6 @@ components: $ref: "#/components/schemas/PostalAddress" us_bank_account: $ref: "#/components/schemas/UsBankAccountAddress" - created_at: - type: string - readOnly: true - format: date-time - description: Time when this object was created. Expressed in ISO 8601 format. - example: "2020-07-10 15:00:00.000" - updated_at: - type: string - readOnly: true - format: date-time - description: Time when this object was last updated. Expressed in ISO 8601 format. - example: "2021-07-11 15:34:00.000" PostalAddress: type: object description: |- @@ -2355,7 +2141,7 @@ components: purpose: type: string description: | - What the File will be used for. We may add additional possible values for this enum over time; + What the File will be used for. We may add additional possible values for this enum over time; your application should be able to handle such additions gracefully. grant_letter: A grant letter tax_document: A tax document @@ -2418,7 +2204,6 @@ components: required: - organization_id - amount - - payment_id properties: id: type: string @@ -2457,27 +2242,12 @@ components: description: |- The unique identifier for the payment that the transaction is associated with. example: "pay_1LaXpKGUcADgqoEMl0Cx0Ygg" - payment: - $ref: "#/components/schemas/Payment" - payment_details: - $ref: "#/components/schemas/PaymentDetails" attachment_file_id: type: string description: |- The unique identifier for the file that is attached to the transaction. This is useful if you want to attach a letter or another document to the transaction. example: "file_1LaXpKGUcADgqoEMl0Cx0Ygg" - status: - type: string - description: The status of the transaction - example: "pending" - readOnly: true - enum: - - pending - - submitted - - completed - - canceled - - rejected created_at: type: string format: date-time @@ -2589,7 +2359,7 @@ components: properties: irs_group_exemption_number: type: string - description: This is a four-digit internal IRS number assigned to central/parent entity holding group exemption letters. + description: This is a four-digit internal IRS number assigned to central/parent entity holding group exemption letters. irs_subsection_code: type: string description: The IRS subsection code for the entity @@ -2824,12 +2594,6 @@ components: type: string description: The unique identifier for the organization that will receive the payment example: "org_1234567890" - address_id: - type: string - description: |- - The identifier for the address that will receive the payment. - If not specified, the primary address for the organization will be used. - example: "addr_1LaXpKGUcADgqoEMl0Cx0Ygg" amount: type: integer format: int64 @@ -2867,6 +2631,11 @@ components: readOnly: true submission: $ref: "#/components/schemas/PaymentReference" + transactions: + type: array + description: The list of transactions for the payment + items: + $ref: "#/components/schemas/Transaction" PaymentList: description: A list of payments properties: @@ -3101,6 +2870,81 @@ components: This is necessary to verify that the webhook is coming from Chariot. While this parameter is optional, it is highly recommended to pass a value for the secret and implement webhook signature verification. + CreatePaymentRequest: + description: |- + The request to create payments and their corresponding transactions. + The organization and amount are required. + The transactions array should contain the list of transactions associated with the payment. The amounts + in the transactions should sum up to the payment amount. + required: true + content: + application/json: + schema: + type: object + required: + - organization_id + - amount + - transactions + properties: + organization_id: + type: string + description: The ID of the organization that will receive the payment. + example: "org_1234567890" + amount: + type: integer + format: int64 + description: The payment amount in USD cents. Must be a positive amount. + example: 10000 + description: + type: string + description: |- + A description of the payment that will be displayed to the receiving organization. + example: "Payment to Nonprofit" + transactions: + type: array + description: The list of transactions associated with the payment + items: + type: object + description: | + The request to create a transaction. + required: + - amount + properties: + amount: + type: integer + format: int64 + description: The transaction amount in minor currency units (cents) + example: 10000 + currency: + type: string + description: The currency code for the transaction + example: "USD" + default: "USD" + description: + type: string + description: | + A description of the transaction. + This description is displayed to the receiving organization. + example: "Transaction to Nonprofit" + donation: + $ref: "#/components/schemas/Donation" + donors: + type: array + description: The list of donors for the transaction + items: + $ref: "#/components/schemas/Donor" + # TODO: we don't have the ability to create files yet, so leaving this out for now + # attachment_file_id: + # type: string + # description: |- + # The unique identifier for the file that is attached to the transaction. + # This is useful if you want to attach a letter or another document to the transaction. + # example: "file_1LaXpKGUcADgqoEMl0Cx0Ygg" + metadata: + type: object + description: Additional metadata for the transaction + additionalProperties: + type: string UpdateEventSubscriptionRequest: description: The request body for creating an event subscription required: true