subbyCharges
Individual payment attempts.
https://sandbox-api.mysubbyapp.com/v1
POST
/chargesCreate a one-off charge
Charges a customer's default payment method once, outside their subscription schedule.
Metered on successful live writescharges:write
Request example
curl --request POST \
--url 'https://sandbox-api.mysubbyapp.com/v1/charges' \
--header 'Authorization: Bearer sk_test_YOUR_SECRET_KEY'Add a JSON body matching the request schema below and a Content-Type: application/json header.
Parameters
Idempotency-Keyheader · string Makes retries safe. Replays return the original response and are not metered.
Request body schema
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"customer",
"amount",
"currency"
],
"properties": {
"customer": {
"type": "string"
},
"amount": {
"type": "integer",
"minimum": 100,
"description": "Kobo."
},
"currency": {
"type": "string",
"enum": [
"NGN"
]
},
"description": {
"type": "string",
"maxLength": 200
},
"payment_method": {
"type": "string",
"description": "Defaults to the customer's default payment method."
},
"metadata": {
"type": "object",
"maxProperties": 20,
"propertyNames": {
"maxLength": 40
},
"additionalProperties": {
"type": "string",
"maxLength": 500
}
}
}
}
}
}
}Responses
201 The charge. A declined payment still returns 201 with `status` `failed`.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "chg_3Wd8Lk"
},
"object": {
"const": "charge"
},
"amount": {
"type": "integer"
},
"currency": {
"const": "NGN"
},
"status": {
"type": "string",
"enum": [
"pending",
"succeeded",
"failed"
]
},
"customer": {
"type": "string"
},
"subscription": {
"type": [
"string",
"null"
]
},
"attempt_number": {
"type": "integer"
},
"will_retry": {
"type": "boolean"
},
"next_retry_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"failure_code": {
"type": [
"string",
"null"
]
},
"failure_message": {
"type": [
"string",
"null"
]
},
"payment_method": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "pm_2Hx9"
},
"type": {
"type": "string",
"enum": [
"card",
"bank_account",
"ussd"
]
},
"brand": {
"type": [
"string",
"null"
],
"example": "verve"
},
"last4": {
"type": [
"string",
"null"
]
},
"bank_name": {
"type": [
"string",
"null"
]
},
"exp_month": {
"type": [
"integer",
"null"
]
},
"exp_year": {
"type": [
"integer",
"null"
]
}
}
},
"processor": {
"type": "string",
"enum": [
"paystack",
"flutterwave",
"simulator"
]
},
"description": {
"type": [
"string",
"null"
]
},
"paid_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"metadata": {
"type": "object",
"maxProperties": 20,
"propertyNames": {
"maxLength": 40
},
"additionalProperties": {
"type": "string",
"maxLength": 500
}
},
"livemode": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
}400 Invalid request.
{
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error"
],
"properties": {
"success": {
"const": false
},
"error": {
"type": "object",
"required": [
"type",
"code",
"message",
"request_id"
],
"properties": {
"type": {
"type": "string",
"enum": [
"authentication_error",
"permission_error",
"invalid_request_error",
"state_error",
"idempotency_error",
"rate_limit_error",
"api_error"
]
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"param": {
"type": [
"string",
"null"
]
},
"request_id": {
"type": "string"
},
"doc_url": {
"type": "string",
"format": "uri"
}
}
}
}
}
}
}422 Valid request that conflicts with the object's state.
{
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error"
],
"properties": {
"success": {
"const": false
},
"error": {
"type": "object",
"required": [
"type",
"code",
"message",
"request_id"
],
"properties": {
"type": {
"type": "string",
"enum": [
"authentication_error",
"permission_error",
"invalid_request_error",
"state_error",
"idempotency_error",
"rate_limit_error",
"api_error"
]
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"param": {
"type": [
"string",
"null"
]
},
"request_id": {
"type": "string"
},
"doc_url": {
"type": "string",
"format": "uri"
}
}
}
}
}
}
}GET
/chargesList charges
Not meteredcharges:read
Request example
curl --request GET \
--url 'https://sandbox-api.mysubbyapp.com/v1/charges' \
--header 'Authorization: Bearer sk_test_YOUR_SECRET_KEY'Parameters
limitquery · integer starting_afterquery · string ending_beforequery · string customerquery · string subscriptionquery · string statusquery · string Responses
200 Charges, newest first.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "chg_3Wd8Lk"
},
"object": {
"const": "charge"
},
"amount": {
"type": "integer"
},
"currency": {
"const": "NGN"
},
"status": {
"type": "string",
"enum": [
"pending",
"succeeded",
"failed"
]
},
"customer": {
"type": "string"
},
"subscription": {
"type": [
"string",
"null"
]
},
"attempt_number": {
"type": "integer"
},
"will_retry": {
"type": "boolean"
},
"next_retry_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"failure_code": {
"type": [
"string",
"null"
]
},
"failure_message": {
"type": [
"string",
"null"
]
},
"payment_method": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "pm_2Hx9"
},
"type": {
"type": "string",
"enum": [
"card",
"bank_account",
"ussd"
]
},
"brand": {
"type": [
"string",
"null"
],
"example": "verve"
},
"last4": {
"type": [
"string",
"null"
]
},
"bank_name": {
"type": [
"string",
"null"
]
},
"exp_month": {
"type": [
"integer",
"null"
]
},
"exp_year": {
"type": [
"integer",
"null"
]
}
}
},
"processor": {
"type": "string",
"enum": [
"paystack",
"flutterwave",
"simulator"
]
},
"description": {
"type": [
"string",
"null"
]
},
"paid_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"metadata": {
"type": "object",
"maxProperties": 20,
"propertyNames": {
"maxLength": 40
},
"additionalProperties": {
"type": "string",
"maxLength": 500
}
},
"livemode": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
},
"meta": {
"type": "object",
"required": [
"has_more",
"limit"
],
"properties": {
"has_more": {
"type": "boolean"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"limit": {
"type": "integer"
}
}
}
}
}
}
}GET
/charges/{id}Retrieve a charge
Not meteredcharges:read
Request example
curl --request GET \
--url 'https://sandbox-api.mysubbyapp.com/v1/charges/{id}' \
--header 'Authorization: Bearer sk_test_YOUR_SECRET_KEY'Parameters
idpath · string · requiredexpand[]query · array Related fields to expand, up to 4.
Responses
200 The charge.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "chg_3Wd8Lk"
},
"object": {
"const": "charge"
},
"amount": {
"type": "integer"
},
"currency": {
"const": "NGN"
},
"status": {
"type": "string",
"enum": [
"pending",
"succeeded",
"failed"
]
},
"customer": {
"type": "string"
},
"subscription": {
"type": [
"string",
"null"
]
},
"attempt_number": {
"type": "integer"
},
"will_retry": {
"type": "boolean"
},
"next_retry_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"failure_code": {
"type": [
"string",
"null"
]
},
"failure_message": {
"type": [
"string",
"null"
]
},
"payment_method": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "pm_2Hx9"
},
"type": {
"type": "string",
"enum": [
"card",
"bank_account",
"ussd"
]
},
"brand": {
"type": [
"string",
"null"
],
"example": "verve"
},
"last4": {
"type": [
"string",
"null"
]
},
"bank_name": {
"type": [
"string",
"null"
]
},
"exp_month": {
"type": [
"integer",
"null"
]
},
"exp_year": {
"type": [
"integer",
"null"
]
}
}
},
"processor": {
"type": "string",
"enum": [
"paystack",
"flutterwave",
"simulator"
]
},
"description": {
"type": [
"string",
"null"
]
},
"paid_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"metadata": {
"type": "object",
"maxProperties": 20,
"propertyNames": {
"maxLength": 40
},
"additionalProperties": {
"type": "string",
"maxLength": 500
}
},
"livemode": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
}404 Object or route not found in this environment.
{
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error"
],
"properties": {
"success": {
"const": false
},
"error": {
"type": "object",
"required": [
"type",
"code",
"message",
"request_id"
],
"properties": {
"type": {
"type": "string",
"enum": [
"authentication_error",
"permission_error",
"invalid_request_error",
"state_error",
"idempotency_error",
"rate_limit_error",
"api_error"
]
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"param": {
"type": [
"string",
"null"
]
},
"request_id": {
"type": "string"
},
"doc_url": {
"type": "string",
"format": "uri"
}
}
}
}
}
}
}POST
/charges/{id}/retryRetry a failed charge now
Use when a customer asks to pay immediately. Automatic retries don't need this and are free.
Metered on successful live writescharges:write
Request example
curl --request POST \
--url 'https://sandbox-api.mysubbyapp.com/v1/charges/{id}/retry' \
--header 'Authorization: Bearer sk_test_YOUR_SECRET_KEY'Add a JSON body matching the request schema below and a Content-Type: application/json header.
Parameters
idpath · string · requiredIdempotency-Keyheader · string Makes retries safe. Replays return the original response and are not metered.
Request body schema
{
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"payment_method": {
"type": "string"
}
}
}
}
}
}Responses
201 The new charge attempt.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "chg_3Wd8Lk"
},
"object": {
"const": "charge"
},
"amount": {
"type": "integer"
},
"currency": {
"const": "NGN"
},
"status": {
"type": "string",
"enum": [
"pending",
"succeeded",
"failed"
]
},
"customer": {
"type": "string"
},
"subscription": {
"type": [
"string",
"null"
]
},
"attempt_number": {
"type": "integer"
},
"will_retry": {
"type": "boolean"
},
"next_retry_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"failure_code": {
"type": [
"string",
"null"
]
},
"failure_message": {
"type": [
"string",
"null"
]
},
"payment_method": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "pm_2Hx9"
},
"type": {
"type": "string",
"enum": [
"card",
"bank_account",
"ussd"
]
},
"brand": {
"type": [
"string",
"null"
],
"example": "verve"
},
"last4": {
"type": [
"string",
"null"
]
},
"bank_name": {
"type": [
"string",
"null"
]
},
"exp_month": {
"type": [
"integer",
"null"
]
},
"exp_year": {
"type": [
"integer",
"null"
]
}
}
},
"processor": {
"type": "string",
"enum": [
"paystack",
"flutterwave",
"simulator"
]
},
"description": {
"type": [
"string",
"null"
]
},
"paid_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"metadata": {
"type": "object",
"maxProperties": 20,
"propertyNames": {
"maxLength": 40
},
"additionalProperties": {
"type": "string",
"maxLength": 500
}
},
"livemode": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
}422 Valid request that conflicts with the object's state.
{
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error"
],
"properties": {
"success": {
"const": false
},
"error": {
"type": "object",
"required": [
"type",
"code",
"message",
"request_id"
],
"properties": {
"type": {
"type": "string",
"enum": [
"authentication_error",
"permission_error",
"invalid_request_error",
"state_error",
"idempotency_error",
"rate_limit_error",
"api_error"
]
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"param": {
"type": [
"string",
"null"
]
},
"request_id": {
"type": "string"
},
"doc_url": {
"type": "string",
"format": "uri"
}
}
}
}
}
}
}