{ "openapi": "3.0.1", "info": { "title": "Payments APIs", "description": "The Payment APIs include a variety of operations that allow users to manage payment methods, refill wallet and balance check of accounts.", "version": "1.0.0" }, "servers": [ { "url": "https://api-sandbox.sendpro360.pitneybowes.com/shippingpaymentmgmt", "description": "Sandbox Server" }, { "url": "https://api.sendpro360.pitneybowes.com/shippingpaymentmgmt", "description": "Production Server (uses live data)" }, { "url": "https://api-ppd.shipping360.pitneybowes.com/ca/shippingpaymentmgmt", "description": "Sandbox Server for Canada" }, { "url": "https://api.shipping360.pitneybowes.com/ca/shippingpaymentmgmt", "description": "Production Server for Canada" } ], "tags": [ { "name": "Payment", "description": "" } ], "paths": { "/api/v1/payments/methods": { "get": { "tags": [ "Payment" ], "summary": "Get Payment Methods", "description": "This operation returns all payment methods (Credit Card, Trust Account , Reserve and Purchase Power accounts) associated with the carrier account (USPS)", "operationId": "getPaymentMethods", "parameters": [ { "name": "X-PB-Developer-Partner-ID", "description": "This is the Developer Partner ID. When the developer is the only partner, this field is not required.", "required": false, "in": "header", "schema": { "type": "string" } }, { "name": "carrierAccountId", "description": "A unique identifier assigned to the specific carrier account. Its value can be referred from the response of `Get Carrier Accounts` API", "required": true, "in": "query", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "The available payment methods returned successfully", "headers": { "X-Pb-Transactionid": { "description": "The X-PB-TransactionId is unique id for this request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/paymentmethods" } } } }, "400": { "description": "Invalid or Bad Request", "$ref": "#/components/responses/BadRequestError" }, "401": { "description": "Unauthorized Error", "$ref": "#/components/responses/UnauthorizedError" }, "500": { "description": "Internal Server Error", "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/payments/accounts/balance": { "get": { "tags": [ "Payment" ], "summary": "Get Payment account balance", "description": "This operation returns balance of Wallet or PB Bank (GFS payment method) accounts.", "operationId": "getPaymentBalance", "parameters": [ { "name": "X-PB-Developer-Partner-ID", "description": "This is the Developer Partner ID. When the developer is the only partner, this field is not required.", "required": false, "in": "header", "schema": { "type": "string" } }, { "name": "accountType", "description": "An identifier to get balance of Wallet or PB Bank. It accepts `WALLET` for fetching postage balance and `PBBANK` for fetching GFS balance.", "required": true, "in": "query", "schema": { "type": "string", "enum": [ "WALLET", "PBBANK" ] } }, { "name": "carrierAccountId", "description": "A unique identifier assigned to the specific carrier account. Its value can be referred from the response of `Get Carrier Accounts` API. It is required when accountType is `WALLET`", "in": "query", "schema": { "type": "string" } }, { "name": "locationId", "description": "It specifies the Location Id on which GFS payment method is associated. Its value can be refered from response of `Get Location Details` API. It is required when accountType is `PBBANK`.", "in": "query", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Returns account balance", "headers": { "X-Pb-Transactionid": { "description": "The X-PB-TransactionId is unique id for this request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/balanceResponse" } } } }, "400": { "description": "Invalid or Bad Request", "$ref": "#/components/responses/BadRequestError" }, "401": { "description": "Unauthorized Error", "$ref": "#/components/responses/UnauthorizedError" }, "500": { "description": "Internal Server Error", "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/payments/methods/rank": { "patch": { "tags": [ "Payment" ], "summary": "Set rank of payment method", "description": "This operation sets rank (priority) of payment method for postage refill and subscription billing .", "operationId": "setPaymentMethodRank", "parameters": [ { "name": "X-PB-Developer-Partner-ID", "description": "This is the Developer Partner ID. When the developer is the only partner, this field is not required.", "required": false, "in": "header", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "carrierAccountId", "paymentMethodId", "paymentMethodRankFor", "paymentMethodRank" ], "properties": { "carrierAccountId": { "type": "string", "description": "It specifies the unique carrier account id. Its value can be referred from `Get Carrier Accounts` API", "example": "gOpvB5GjV8r" }, "paymentMethodId": { "type": "string", "description": "It specifies the payment method id. Its value can be referred from response of `Get Payment Methods` API.", "example": "4b60dba7-8f01-4f4f-9900-956f1e4cb7bf" }, "paymentMethodRankFor": { "type": "string", "description": "This is to specify Postage or Subscription rank to be set", "enum": [ "POSTAGE", "SUBSCRIPTION" ], "example": "POSTAGE" }, "paymentMethodRank": { "type": "integer", "description": "It specify the rank(priority) for the payment method. It takes numeric value, 1 being the highest priority", "example": 1 } } }, "example": { "carrierAccountId": "gOpvB5GjV8r", "paymentMethodId": "4b60dba7-8f01-4f4f-9900-956f1e4cb7bf", "paymentMethodRankFor": "POSTAGE", "paymentMethodRank": 1 } } } }, "responses": { "200": { "description": "Updated rank of Payment Method", "content": {} }, "400": { "description": "Invalid or Bad Request", "$ref": "#/components/responses/BadRequestError" }, "401": { "description": "Unauthorized Error", "$ref": "#/components/responses/UnauthorizedError" }, "500": { "description": "Internal Server Error", "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/payments/methods/status": { "patch": { "tags": [ "Payment" ], "summary": "Set Payment Method Status", "description": "This operation sets the Payment Method active or inactive.", "operationId": "setPaymentMethodStatus", "parameters": [ { "name": "X-PB-Developer-Partner-ID", "description": "This is the Developer Partner ID. When the developer is the only partner, this field is not required.", "required": false, "in": "header", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "carrierAccountId", "paymentMethodId", "paymentMethodStatus" ], "properties": { "carrierAccountId": { "type": "string", "description": "A unique identifier assigned to the specific carrier account. Its value can be referred from the response of `Get Carrier Accounts` API.", "example": "gOpvB5GjV8r" }, "paymentMethodId": { "type": "string", "description": "It specifies payment method id. Its value can be referred from response of `Get Payment Methods` API.", "example": "4b60dba7-8f01-4f4f-9900-956f1e4cb7bf" }, "paymentMethodStatus": { "type": "string", "description": "It specified the status to mark ACTIVE or INACTIVE", "enum": [ "ACTIVE", "INACTIVE" ], "example": "ACTIVE" } }, "example": { "carrierAccountId": "gOpvB5GjV8r", "paymentMethodId": "4b60dba7-8f01-4f4f-9900-956f1e4cb7bf", "paymentMethodStatus": "ACTIVE" } } } } }, "responses": { "200": { "description": "Set Payment Method Status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } } }, "400": { "description": "Invalid or Bad Request", "$ref": "#/components/responses/BadRequestError" }, "401": { "description": "Unauthorized Error", "$ref": "#/components/responses/UnauthorizedError" }, "500": { "description": "Internal Server Error", "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/payments/wallet/refill": { "post": { "tags": [ "Payment" ], "summary": "Wallet Refill", "description": "This operation is used to refill amount to the Wallet", "operationId": "walletRefill", "parameters": [ { "name": "X-PB-Developer-Partner-ID", "description": "This is the Developer Partner ID. When the developer is the only partner, this field is not required.", "required": false, "in": "header", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "carrierAccountId", "amount" ], "properties": { "carrierAccountId": { "type": "string", "description": "A unique identifier assigned to the specific carrier account. Its value can be referred from the response of `Get Carrier Accounts` API.", "example": "gOpvB5GjV8r" }, "amount": { "type": "number", "description": "It specified the required amount with which wallet is to refill.", "example": 10 }, "costAccountId": { "type": "string", "description": "It specified the cost account Id with which this transaction can be associated. Its value can be referred from response of `Get Cost Accounts` API", "example": "abc" } }, "example": { "carrierAccountId": "gOpvB5GjV8r", "amount": 10 } } } } }, "responses": { "200": { "description": "Wallet refill is successful", "headers": { "X-PB-TransactionId": { "description": "The X-PB-TransactionId is unique id for this request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/refillresponse" } } } }, "400": { "description": "Invalid or Bad Request", "$ref": "#/components/responses/BadRequestError" }, "401": { "description": "Unauthorized Error", "$ref": "#/components/responses/UnauthorizedError" }, "500": { "description": "Internal Server Error", "$ref": "#/components/responses/InternalServerError" } } } } }, "components": { "schemas": { "error": { "type": "object", "properties": { "message": { "type": "string", "description": "This is HTTP 401 Unauthorized response status code, that indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource." } }, "required": [ "message" ] }, "Errors": { "type": "array", "items": { "type": "object", "properties": { "errorCode": { "type": "string", "description": "Error code(s) that appear due to HTTP 400- Invalid or Bad Request, e.g. validation-error.", "example": "validation_error" }, "errorDescription": { "type": "string", "description": "The HTTP 400 Bad Request response status code indicates that the server cannot process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).", "example": "Error while getting rates for carrier with carrierAccount eRMnRx4mzPP." }, "additionalCode": { "type": "string", "description": "A unique identifier for the error, for example 1101055, 0100008, or 1021126." }, "additionalInfo": { "type": "string", "description": "This is an additional information about the error. This error 'Invalid Request' might appear due to invalid dimension, weight, or serviceid, or if the information is missing." }, "additionalParameters": { "type": "array", "items": { "type": "string", "description": "The field(s) that might be incorrect in the request." } } } } }, "NotFoundErrors": { "type": "array", "items": { "type": "object", "properties": { "errorCode": { "type": "string", "example": "not_found", "description": "Error code(s) that appear due HTTP 404 Page or File not found." }, "errorDescription": { "type": "string", "example": "resource not found", "description": "The HTTP 404 Not Found response status code indicates that the server cannot find the requested resource." }, "additionalCode": { "type": "string", "description": "A unique identifier for the error, for example 0100025, 1110017, or 1090001." }, "additionalInfo": { "type": "string", "description": "Additional information about the error. This error 'Not Found' might appear due to `Shipment Not Found`, `No Shipments to close`, or `Original Transaction not found`." }, "additionalParameters": { "type": "array", "items": { "type": "string", "description": "The field(s) that might be incorrect in the request." } } } } }, "paymentmethods": { "type": "object", "properties": { "paymentMethods": { "type": "array", "description": "It provides list of payment methods available", "items": { "type": "object", "properties": { "accountNumber": { "type": "string", "description": "It displays the account number of the specific payment method", "example": "1111" }, "billingAddress": { "type": "object", "description": "It displays the address details associated with payment method", "properties": { "addressLine1": { "type": "string", "example": "wall2" }, "addressLine2": { "type": "string", "example": "apartment #2" }, "cityTown": { "type": "string", "example": "Danbury" }, "countryCode": { "type": "string", "example": "US" }, "postalCode": { "type": "string", "example": "12201-7050" }, "residential": { "type": "boolean", "example": false }, "stateProvince": { "type": "string", "example": "NY" } } }, "createdDate": { "type": "string", "description": "It displays the date when payment method was registered", "example": "2022-09-15 18:05:30" }, "ranks": { "type": "object", "description": "It displays the priority set for this payment method while dispense. It shows the numeric value where 1 being the highest priority.", "properties": { "postage": { "type": "number", "description": "It displays the priority for adding funds to the wallet.", "example": 1 }, "subscription": { "type": "number", "description": "It displays the priority while renewal of subscription.", "example": 2 } } }, "expirationDate": { "type": "string", "description": "It displays the expiration of payment method (if applicable).", "example": "02/2026" }, "paymentMethodCode": { "type": "string", "description": "It displays the payment methods. For example- `CC_Visa`, `CC_Master`, `CC_Discover` and `GFS`.", "example": "CC_Visa" }, "paymentMethodDescription": { "type": "string", "description": "It displays the description of this payment method.", "example": "Visa Card" }, "paymentMethodId": { "type": "string", "description": "It displays the unique id for this payment method.", "example": "1bcf3299-ab63-43bc-9109-18fe60e26136" }, "paymentMethodStatus": { "type": "string", "description": "It displays the payment method whether Active or Inactive.", "enum": [ "ACTIVE", "INACTIVE" ], "example": "ACTIVE" } } }, "example": [ { "accountNumber": "1111", "billingAddress": { "addressLine1": "wall2", "cityTown": "Danbury", "countryCode": "US", "postalCode": "12201-7050", "residential": false, "stateProvince": "NY" }, "createdDate": "2022-09-15 18:05:30", "ranks": { "postage": 1 }, "expirationDate": "02/2026", "paymentMethodCode": "CC_Visa", "paymentMethodDescription": "Visa Card", "paymentMethodId": "1bcf3299-ab63-43bc-9109-18fe60e26136", "paymentMethodStatus": "ACTIVE" }, { "accountNumber": "9818", "billingAddress": { "addressLine1": "wall2", "addressLine2": "apartment #2", "cityTown": "Danbury", "countryCode": "US", "postalCode": "12201-7050", "residential": false, "stateProvince": "NY" }, "createdDate": "2021-08-16 13:13:32", "ranks": { "postage": 2 }, "expirationDate": "09/2022", "paymentMethodCode": "CC_Discover", "paymentMethodDescription": "Discover Card", "paymentMethodId": "4b60dba7-8f01-4f4f-9900-956f1e4cb7bf", "paymentMethodStatus": "ACTIVE" } ] } } }, "balanceResponse": { "type": "object", "properties": { "walletAccount": { "type": "object", "description": "It would show when accountType is `WALLET` in request.", "properties": { "currency": { "type": "string", "description": "It displays the currency code", "example": "USD" }, "balanceAvailable": { "type": "number", "description": "It displays the available balance with this account", "example": 1000 }, "pendingBalance": { "type": "number", "description": "It displays the pending balance", "example": 1100 } } }, "trustAccount": { "type": "object", "description": "It would display when accountType is `PBBANK` and trust account is available", "properties": { "accountId": { "type": "string", "description": "It displays the account id with this account", "example": "58545575" }, "accountEnabled": { "type": "boolean", "description": "It displays if account is enabled.", "example": true }, "balanceAvailable": { "type": "number", "description": "It displays the balance available for this account", "example": 1100 } } }, "purchasePowerAccount": { "type": "object", "description": "It would display when accountType is `PBBANK` and purchase power account is available", "properties": { "accountId": { "type": "string", "description": "It displays the account id associated with this account", "example": "8000900000242952" }, "accountEnabled": { "type": "boolean", "description": "It displays if account is enabled", "example": true }, "creditLimit": { "type": "number", "description": "It displays the credit limit for this account", "example": 500 }, "availableCredit": { "type": "number", "description": "It displays the avaiable credit with this account", "example": -25426.5 }, "balanceCurrent": { "type": "number", "description": "It displays the current balance with this account", "example": 10 }, "minPayDate": { "type": "string", "description": "It displays the min pay date", "example": "0000-00-00" }, "minPayAmount": { "type": "number", "description": "It displays the minimum pay amount", "example": 10 } } }, "reserveAccount": { "type": "object", "description": "It would show when accountType is `PBBANK` in request and reserve account is available.", "properties": { "accountId": { "type": "string", "description": "It displays the account id with this account", "example": "58545575" } } } } }, "Empty": { "title": "Empty Schema", "type": "object" }, "refillresponse": { "type": "object", "properties": { "requestedAmount": { "type": "number", "description": "It displays the amount with which wallet refill is done", "example": 10 }, "balanceAvailable": { "type": "number", "description": "It displays the available balance", "example": 3734.8 }, "totalAmount": { "type": "number", "description": "It displays the total amount which deducted from payment method", "example": 10.35 }, "status": { "type": "string", "description": "It displays the status of the transaction", "enum": [ "SUCCESS", "PENDING", "FAILED" ], "example": "SUCCESS" }, "transactionDetails": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string", "description": "It displays the account Id of the payment method used to refill.", "example": "1111" }, "accountType": { "type": "string", "description": "It displays the account type of the payment method used to refill.", "example": "Credit Card" }, "amount": { "type": "number", "description": "It displays the amount which wallet is credited with.", "example": 10 } } }, "example": [ { "accountId": "1111", "accountType": "Credit Card", "amount": 10 }, { "accountId": "1111", "accountType": "Credit Card Fees", "amount": 0.35 } ] } } } }, "responses": { "UnauthorizedError": { "description": "The request could not be authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "InternalServerError": { "description": "The request could not be completed due to an internal error.", "content": {} }, "BadRequestError": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } } } }, "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic" }, "bearerAuth": { "type": "http", "scheme": "bearer" } } } }