use std::sync::Arc;
use serde::Serialize;
use serde_json::Value;
use crate::core::encoding::{encode_segment, to_json_vec};
use crate::core::error::{DelopayError, Result};
use crate::core::models::common::{Currency, ListResponse, PayoutType};
use crate::core::models::payout::PayoutResponse;
use crate::http::client::Inner;
use crate::http::transport::HttpMethod;
use crate::resources::ValidateRequest;
#[derive(Debug, Clone)]
pub struct Payouts {
inner: Arc<Inner>,
}
impl Payouts {
pub(crate) fn new(inner: Arc<Inner>) -> Self {
Self { inner }
}
pub async fn create(&self, params: &PayoutCreateRequest) -> Result<PayoutResponse> {
params.validate()?;
let body = to_json_vec(params)?;
self.inner
.request(HttpMethod::Post, "/payouts/create", Some(&body), &[], None)
.await
}
pub async fn retrieve(&self, payout_id: &str) -> Result<PayoutResponse> {
let path = format!("/payouts/{}", encode_segment(payout_id));
self.inner
.request(HttpMethod::Get, &path, None, &[], None)
.await
}
pub async fn update(
&self,
payout_id: &str,
params: &PayoutUpdateRequest,
) -> Result<PayoutResponse> {
params.validate()?;
let path = format!("/payouts/{}", encode_segment(payout_id));
let body = to_json_vec(params)?;
self.inner
.request(HttpMethod::Put, &path, Some(&body), &[], None)
.await
}
pub async fn confirm(
&self,
payout_id: &str,
params: Option<&PayoutUpdateRequest>,
) -> Result<PayoutResponse> {
let path = format!("/payouts/{}/confirm", encode_segment(payout_id));
let body: Option<Vec<u8>> = match params {
Some(p) => {
p.validate()?;
Some(to_json_vec(p)?)
}
None => None,
};
self.inner
.request(HttpMethod::Post, &path, body.as_deref(), &[], None)
.await
}
pub async fn fulfill(&self, payout_id: &str) -> Result<PayoutResponse> {
let path = format!("/payouts/{}/fulfill", encode_segment(payout_id));
self.inner
.request(HttpMethod::Post, &path, None, &[], None)
.await
}
pub async fn cancel(&self, payout_id: &str) -> Result<PayoutResponse> {
let path = format!("/payouts/{}/cancel", encode_segment(payout_id));
self.inner
.request(HttpMethod::Post, &path, None, &[], None)
.await
}
pub async fn list(
&self,
params: Option<&PayoutListParams>,
) -> Result<ListResponse<PayoutResponse>> {
let query = params.map(PayoutListParams::to_query).unwrap_or_default();
self.inner
.request(HttpMethod::Get, "/payouts/list", None, &query, None)
.await
}
pub async fn list_by_profile(
&self,
params: Option<&PayoutListParams>,
) -> Result<ListResponse<PayoutResponse>> {
let query = params.map(PayoutListParams::to_query).unwrap_or_default();
self.inner
.request(HttpMethod::Get, "/payouts/profile/list", None, &query, None)
.await
}
pub async fn list_by_filter(&self, params: &Value) -> Result<ListResponse<PayoutResponse>> {
let body = to_json_vec(params)?;
self.inner
.request(HttpMethod::Post, "/payouts/list", Some(&body), &[], None)
.await
}
pub async fn filters(&self, query: &[(&str, String)]) -> Result<Value> {
self.inner
.request(HttpMethod::Get, "/payouts/filter", None, query, None)
.await
}
pub async fn filters_by_profile(&self, query: &[(&str, String)]) -> Result<Value> {
self.inner
.request(
HttpMethod::Get,
"/payouts/profile/filter",
None,
query,
None,
)
.await
}
pub async fn aggregate(&self, query: &[(&str, String)]) -> Result<Value> {
self.inner
.request(HttpMethod::Get, "/payouts/aggregate", None, query, None)
.await
}
pub async fn aggregate_by_profile(&self, query: &[(&str, String)]) -> Result<Value> {
self.inner
.request(
HttpMethod::Get,
"/payouts/profile/aggregate",
None,
query,
None,
)
.await
}
pub async fn manual_update(&self, payout_id: &str, params: &Value) -> Result<PayoutResponse> {
let path = format!("/payouts/{}/manual-update", encode_segment(payout_id));
let body = to_json_vec(params)?;
self.inner
.request(HttpMethod::Put, &path, Some(&body), &[], None)
.await
}
}
#[derive(Debug, Clone, Default)]
pub struct PayoutListParams {
pub customer_id: Option<String>,
pub starting_after: Option<String>,
pub ending_before: Option<String>,
pub limit: Option<i64>,
pub created: Option<String>,
pub start_time: Option<String>,
pub end_time: Option<String>,
}
impl PayoutListParams {
fn to_query(&self) -> Vec<(&'static str, String)> {
let mut q = Vec::new();
if let Some(v) = &self.customer_id {
q.push(("customer_id", v.clone()));
}
if let Some(v) = &self.starting_after {
q.push(("starting_after", v.clone()));
}
if let Some(v) = &self.ending_before {
q.push(("ending_before", v.clone()));
}
if let Some(v) = self.limit {
q.push(("limit", v.to_string()));
}
if let Some(v) = &self.created {
q.push(("created", v.clone()));
}
if let Some(v) = &self.start_time {
q.push(("start_time", v.clone()));
}
if let Some(v) = &self.end_time {
q.push(("end_time", v.clone()));
}
q
}
}
#[derive(Debug, Clone, Default, Serialize)]
pub struct PayoutUpdateRequest {
#[serde(skip_serializing_if = "Option::is_none")]
pub merchant_order_reference_id: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub amount: Option<i64>,
#[serde(skip_serializing_if = "Option::is_none")]
pub currency: Option<Currency>,
#[serde(skip_serializing_if = "Option::is_none")]
pub routing: Option<Value>,
#[serde(skip_serializing_if = "Option::is_none")]
pub connector: Option<Vec<String>>,
#[serde(skip_serializing_if = "Option::is_none")]
pub confirm: Option<bool>,
#[serde(skip_serializing_if = "Option::is_none")]
pub payout_type: Option<PayoutType>,
#[serde(skip_serializing_if = "Option::is_none")]
pub payout_method_data: Option<Value>,
#[serde(skip_serializing_if = "Option::is_none")]
pub billing: Option<Value>,
#[serde(skip_serializing_if = "Option::is_none")]
pub customer_id: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub description: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub return_url: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub entity_type: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub metadata: Option<Value>,
#[serde(flatten, skip_serializing_if = "serde_json::Map::is_empty")]
pub extra: serde_json::Map<String, Value>,
}
const PAYOUT_UPDATE_REQUEST_NAMED: &[&str] = &[
"merchant_order_reference_id",
"amount",
"currency",
"routing",
"connector",
"confirm",
"payout_type",
"payout_method_data",
"billing",
"customer_id",
"description",
"return_url",
"entity_type",
"metadata",
];
impl ValidateRequest for PayoutUpdateRequest {
fn validate(&self) -> Result<()> {
for key in self.extra.keys() {
if PAYOUT_UPDATE_REQUEST_NAMED.contains(&key.as_str()) {
return Err(DelopayError::InvalidRequest(format!(
"`extra` key `{key}` collides with a named field on PayoutUpdateRequest"
)));
}
}
Ok(())
}
}
#[derive(Debug, Clone, Default, Serialize)]
pub struct PayoutCreateRequest {
pub amount: i64,
pub currency: Currency,
#[serde(skip_serializing_if = "Option::is_none")]
pub confirm: Option<bool>,
#[serde(skip_serializing_if = "Option::is_none")]
pub auto_fulfill: Option<bool>,
#[serde(skip_serializing_if = "Option::is_none")]
pub payout_type: Option<PayoutType>,
#[serde(skip_serializing_if = "Option::is_none")]
pub payout_method_data: Option<Value>,
#[serde(skip_serializing_if = "Option::is_none")]
pub customer_id: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub description: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub profile_id: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub billing: Option<Value>,
#[serde(skip_serializing_if = "Option::is_none")]
pub metadata: Option<Value>,
#[serde(flatten, skip_serializing_if = "serde_json::Map::is_empty")]
pub extra: serde_json::Map<String, Value>,
}
const PAYOUT_CREATE_REQUEST_NAMED: &[&str] = &[
"amount",
"currency",
"confirm",
"auto_fulfill",
"payout_type",
"payout_method_data",
"customer_id",
"description",
"profile_id",
"billing",
"metadata",
];
impl ValidateRequest for PayoutCreateRequest {
fn validate(&self) -> Result<()> {
for key in self.extra.keys() {
if PAYOUT_CREATE_REQUEST_NAMED.contains(&key.as_str()) {
return Err(DelopayError::InvalidRequest(format!(
"`extra` key `{key}` collides with a named field on PayoutCreateRequest"
)));
}
}
Ok(())
}
}
impl PayoutCreateRequest {
pub fn new(amount: i64, currency: impl Into<Currency>) -> Self {
Self {
amount,
currency: currency.into(),
..Default::default()
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use serde_json::json;
fn full_payout_create_request() -> PayoutCreateRequest {
PayoutCreateRequest {
amount: 100,
currency: "EUR".to_string(),
confirm: Some(true),
auto_fulfill: Some(true),
payout_type: Some("bank".to_string()),
payout_method_data: Some(json!({"iban": "DE00"})),
customer_id: Some("cus_1".to_string()),
description: Some("payout desc".to_string()),
profile_id: Some("pro_1".to_string()),
billing: Some(json!({"country": "DE"})),
metadata: Some(json!({"order_id": "o_1"})),
extra: serde_json::Map::new(),
}
}
#[test]
fn payout_create_request_named_fields_are_complete() {
let value = serde_json::to_value(full_payout_create_request()).unwrap();
let obj = value.as_object().expect("serializes to a JSON object");
for key in obj.keys() {
assert!(
PAYOUT_CREATE_REQUEST_NAMED.contains(&key.as_str()),
"PAYOUT_CREATE_REQUEST_NAMED is missing wire key `{key}` -- \
add it, or PayoutCreateRequest's extra-key collision guard \
will silently stop covering this field"
);
}
}
#[test]
fn validate_rejects_extra_key_colliding_with_named_field() {
let mut req = PayoutCreateRequest::new(100, "EUR");
req.extra.insert("amount".to_string(), json!(999));
let err = req.validate().unwrap_err();
match err {
DelopayError::InvalidRequest(msg) => assert!(msg.contains("amount")),
other => panic!("expected InvalidRequest, got {other:?}"),
}
}
fn full_payout_update_request() -> PayoutUpdateRequest {
PayoutUpdateRequest {
merchant_order_reference_id: Some("ord_1".to_string()),
amount: Some(100),
currency: Some("EUR".to_string()),
routing: Some(json!({"type": "single"})),
connector: Some(vec!["stripe".to_string()]),
confirm: Some(true),
payout_type: Some("bank".to_string()),
payout_method_data: Some(json!({"iban": "DE00"})),
billing: Some(json!({"country": "DE"})),
customer_id: Some("cus_1".to_string()),
description: Some("desc".to_string()),
return_url: Some("https://example.com/r".to_string()),
entity_type: Some("Individual".to_string()),
metadata: Some(json!({"k": "v"})),
extra: serde_json::Map::new(),
}
}
#[test]
fn payout_update_request_named_fields_are_complete() {
let value = serde_json::to_value(full_payout_update_request()).unwrap();
let obj = value.as_object().expect("serializes to a JSON object");
for key in obj.keys() {
assert!(
PAYOUT_UPDATE_REQUEST_NAMED.contains(&key.as_str()),
"PAYOUT_UPDATE_REQUEST_NAMED is missing wire key `{key}` -- \
add it, or PayoutUpdateRequest's extra-key collision guard \
will silently stop covering this field"
);
}
}
use crate::http::mock::{Step, client_with};
const PAYOUT_JSON: &str = r#"{
"payout_id": "po_1", "merchant_id": "mer_1", "amount": 100,
"currency": "EUR", "status": "requires_confirmation"
}"#;
#[tokio::test]
async fn update_puts_to_the_payout_path() {
let (client, mock) = client_with(vec![Step::ok(PAYOUT_JSON)]);
let req = PayoutUpdateRequest {
amount: Some(700),
..Default::default()
};
client.payouts().update("po_1", &req).await.unwrap();
let seen = mock.seen.lock().unwrap();
assert_eq!(seen[0].method, "PUT");
assert_eq!(seen[0].url, "https://api.test/payouts/po_1");
assert_eq!(seen[0].body_json()["amount"], 700);
}
#[tokio::test]
async fn confirm_carries_the_optional_body() {
let (client, mock) = client_with(vec![Step::ok(PAYOUT_JSON), Step::ok(PAYOUT_JSON)]);
client.payouts().confirm("po_1", None).await.unwrap();
let req = PayoutUpdateRequest {
description: Some("go".to_string()),
..Default::default()
};
client.payouts().confirm("po_1", Some(&req)).await.unwrap();
let seen = mock.seen.lock().unwrap();
assert_eq!(seen[0].url, "https://api.test/payouts/po_1/confirm");
assert!(seen[0].body.is_none(), "None params must send no body");
assert_eq!(seen[1].body_json()["description"], "go");
}
#[tokio::test]
async fn list_serializes_cursor_params() {
let (client, mock) = client_with(vec![Step::ok(r#"{"size":0,"data":[]}"#)]);
let params = PayoutListParams {
starting_after: Some("po_9".to_string()),
limit: Some(25),
..Default::default()
};
client.payouts().list(Some(¶ms)).await.unwrap();
let seen = mock.seen.lock().unwrap();
assert_eq!(
seen[0].url,
"https://api.test/payouts/list?starting_after=po_9&limit=25"
);
}
#[tokio::test]
async fn list_by_profile_gets_the_profile_scoped_path() {
let (client, mock) = client_with(vec![Step::ok(r#"{"size":0,"data":[]}"#)]);
let params = PayoutListParams {
limit: Some(10),
..Default::default()
};
client
.payouts()
.list_by_profile(Some(¶ms))
.await
.unwrap();
let seen = mock.seen.lock().unwrap();
assert_eq!(seen[0].method, "GET");
assert_eq!(
seen[0].url,
"https://api.test/payouts/profile/list?limit=10"
);
}
#[tokio::test]
async fn list_by_filter_posts_the_filter_body() {
let (client, mock) = client_with(vec![Step::ok(r#"{"size":0,"data":[]}"#)]);
client
.payouts()
.list_by_filter(&json!({"status": ["success"]}))
.await
.unwrap();
let seen = mock.seen.lock().unwrap();
assert_eq!(seen[0].method, "POST");
assert_eq!(seen[0].url, "https://api.test/payouts/list");
assert_eq!(seen[0].body_json()["status"][0], "success");
}
#[tokio::test]
async fn filters_endpoints_hit_their_paths_with_queries() {
let (client, mock) = client_with(vec![Step::ok("{}"), Step::ok("{}")]);
client
.payouts()
.filters(&[("currency", "EUR".to_string())])
.await
.unwrap();
client.payouts().filters_by_profile(&[]).await.unwrap();
let seen = mock.seen.lock().unwrap();
assert_eq!(
(seen[0].method, seen[0].url.as_str()),
("GET", "https://api.test/payouts/filter?currency=EUR")
);
assert_eq!(
(seen[1].method, seen[1].url.as_str()),
("GET", "https://api.test/payouts/profile/filter")
);
}
#[tokio::test]
async fn aggregate_endpoints_hit_their_paths_with_queries() {
let (client, mock) = client_with(vec![Step::ok("{}"), Step::ok("{}")]);
client
.payouts()
.aggregate(&[("start_time", "2024-01-01".to_string())])
.await
.unwrap();
client.payouts().aggregate_by_profile(&[]).await.unwrap();
let seen = mock.seen.lock().unwrap();
assert_eq!(
(seen[0].method, seen[0].url.as_str()),
(
"GET",
"https://api.test/payouts/aggregate?start_time=2024-01-01"
)
);
assert_eq!(
(seen[1].method, seen[1].url.as_str()),
("GET", "https://api.test/payouts/profile/aggregate")
);
}
#[tokio::test]
async fn manual_update_puts_to_the_encoded_manual_update_path() {
let (client, mock) = client_with(vec![Step::ok(PAYOUT_JSON)]);
client
.payouts()
.manual_update("po/1", &json!({"status": "success"}))
.await
.unwrap();
let seen = mock.seen.lock().unwrap();
assert_eq!(seen[0].method, "PUT");
assert_eq!(seen[0].url, "https://api.test/payouts/po%2F1/manual-update");
assert_eq!(seen[0].body_json()["status"], "success");
}
}