Stripe 国外银行卡支付功能指南(Java)
简介
编写这篇文章的目的就是~~没有什么目的。网上关于stripe银行卡支付代码很多,有写得很好的,但是太多太杂了,不系统。所以我就结合项目中实际应用,总结了一些比较常用的方法,希望能给予各位一些帮助。
当然我的这个指南也不是很完全,以后如果有机会还会继续补充。
Stripe支付步骤
开通stripe账号
这是最最重要的一步,没有账号后面的内容就不用看啦~~
账号开通之后就是要获得密钥了,stripe密钥分为线上环境密钥和测试环境密钥,我们因为只是做测试就申请测试密钥即可,下面所有讨论的东西都是以测试环境为主
密钥有两种:
可发布密钥(pk_test):前端实现stripe接口时用
密钥(sk_test):后端实现stripe方法时用因为是测试并且所有的支付都是我后台这边操作的,我这边只需要用sk_test的即可,线上环境同理
至此所有准备工作都已经准备好了,我们开始实现银行卡支付功能。
Stripe Api 核心功能
下面是官方文档提供的一些资料,因为官方文档是纯英文版,找的比较麻烦,就把一些使用的文档记录下
StripeApi文档Stripe接口返回错误码文档Stripe测试银行卡号
测试账号不想看上面文档的可以用下面这个即可
通用付款成功 4242 4242 4242 4242
stripe支付核心功能很多,包括但不限于Token、Card、Customers、PaymentIntent、PaymentMethod、Source、Charge
我这边因为业务逻辑并不那么广泛,并没有全部涉及到,所有下面只解释我所用到的核心功能
Customers
顾名思义customber就是用户,凡是需要使用银行卡支付的用户都需要在stripe上创建自己的独立账户,并且最好是需要与你业务上的用户保持唯一,当然这是根据实际情况来的,你不唯一也是可以的,如果你想这么做的话。
创建Customers
Stripe.apiKey = your key;
//创建客户时的参数,方便后面识别,具体参数详见api,这里的话推荐description参数必传,这里的值会展示在stripe平台上方便后面观察
Map<String, Object> params = new HashMap<>();
params.put(
"description",
"My First Test Customer (created for API docs)"
);
Customer customer = Customer.create(params);
//stripe平台Customers的唯一标识
String customerId = customer.getId();
Tokens
Token是Stripe用来客户收集敏感卡或者银行账户信息的过程,当用户填写了银行卡的卡号、过期年月、CVC等信息后,Stripe会生成过一个包含这些信息的Token,这样在传输过程中,确保没有敏感的卡数据和我们自己的服务器交互,降低客户真实信息丢失率。我们自身的服务器,取到token,进行支付即可 。
Token不能多次存储和使用,要存储卡的信息供以后使用,可以创建用户。将卡的信息添加给用户。
创建银行卡号相关Token
Stripe.apiKey = your key;
Map<String, Object> card = new HashMap<>();
card.put("number", "4242424242424242");
card.put("exp_month", 2);
card.put("exp_year", 2022);
card.put("cvc", "314");
Map<String, Object> params = new HashMap<>();
params.put("card", card);
Token token = Token.create(params);
//在后面创建银行卡时可以使用,传参过程无需再填写银行卡相关信息
String tokenId = token.getId();
Cards
可以在一个客户上存储多张卡,向该客户收费。您还可以在收件人上存储多个借记卡,以便以后转移到这些借记卡上。
创建Card并与Customers绑定
Customers初次绑定Card时,如果绑定成功,此Card将成为支付时的默认Card。
Stripe.apiKey = your key;
Map<String, Object> retrieveParams = new HashMap<>();
List<String> expandList = new ArrayList<>();
expandList.add("sources");
retrieveParams.put("expand", expandList);
Customer customer =
Customer.retrieve(
"Customers对应id",
retrieveParams,
null
);
Map<String, Object> params = new HashMap<>();
params.put("source", "银行卡的tokenId");
Card card =
(Card) customer.getSources().create(params);
//建议将卡号保存下来
String cardId = card.getId();
修改Customers的支付默认Card
如果Customers有多张Card,需要更改支付时的默认卡片。
Stripe.apiKey = your key;
Map<String, Object> retrieveParams = new HashMap<>();
List<String> expandList = new ArrayList<>();
expandList.add("sources");
retrieveParams.put("expand", expandList);
Customer customer = Customer.retrieve("Customers对应id", retrieveParams,null);
Map<String, Object> params = new HashMap<>();
params.put("default_source", "需要设置为默认Card的Id");
customer.update(params);
修改Card
修改Card只允许修改一下参数,如果多写了其他参数方法会报错
Stripe.apiKey = your key;
Map<String, Object> retrieveParams =
new HashMap<>();
List<String> expandList = new ArrayList<>();
expandList.add("sources");
retrieveParams.put("expand", expandList);
Customer customer =
Customer.retrieve(
"Customers对应id",
retrieveParams,
null
);
Card card =
customer.getSources().retrieve(
"需要修改Card的Id"
);
//修改参数
Map<String, Object> params = new HashMap<>();
params.put("name", "Jenny Rosen");
Card updatedCard = (Card) card.update(params);
删除Card
如果删除的是默认Card,系统会默认按时间顺序寻找到上一次最后添加的卡片并设置为默认Card。
Stripe.apiKey = your key;
Map<String, Object> retrieveParams =
new HashMap<>();
List<String> expandList = new ArrayList<>();
expandList.add("sources");
retrieveParams.put("expand", expandList);
Customer customer =
Customer.retrieve(
"Customers对应id",
retrieveParams,
null
);
Card card =
customer.getSources().retrieve(
"需要删除Card的Id"
);
Card deletedCard = (Card) card.delete();
Charges
要收取信用卡或借记卡的费用,请创建一个Charge对象。您可以检索并退还单个费用以及列出所有费用。费用由唯一的随机ID标识。
PS:stripe的支付有很多种方式,直接从默认卡扣费,或者回调监听扣费等等方式,我这边因为扣费操作都在后台,与前端没有交互,所以就直接用默认卡扣费的方式操作了
Map<String, Object> params = new HashMap<>();
//金额,实际金额*100,最小支付金额是0.5
params.put("amount", 2000);
//货币单位,小写,银行卡扣费货币换算stripe内部自行转换,我们不需要关心
params.put("currency", "aud");
params.put("customer", "Customers对应id");
params.put(
"description",
"My First Test Charge (created for API docs)"
);
//是否立即捕获费用。默认为true。如果为false,则费用会发出授权(或预授权),以后需要捕获。未捕获的费用将在7天内到期。
params.put("capture", true);
Charge charge = Charge.create(params);
//可以实时获取支付状态
if ("succeeded".equals(charge.getStatus())) {
//交易成功后,需要更新我们的订单表,修改业务参数,此处省略
return true;
} else {
return false;
}
Webhook Endpoints
通过API配置Webhook端点,以通知您的Stripe帐户或关联帐户中发生的事件。
自用Java工具类
本工具类只是根据实际业务做的操作,可能与各位支付场景不同,可以根据api文档理解进行改造,以下仅供参考。
<dependency>
<groupId>com.stripe</groupId>
<artifactId>stripe-java</artifactId>
<version>${stripe.version}</version>
</dependency>
/**
* stripe 支付工具类
*
* @author zhouquan
* @date 2021-01-26 13:44:00
*/
@Component
public class StripePayUtils {
private static final String key = "your key";
/**
* 创建初始用户
* @param description 描述-用户编号
* @return
* @throws StripeException
*/
public String createStripeCustomNoCard(String description) throws StripeException {
Stripe.apiKey = key;
Map<String, Object> params = new HashMap<>();
params.put( "description", description);
Customer customer = Customer.create(params);
return customer.getId();
}
/**
* 更新用户绑定银行卡
* @param stripeMemberId 客户stripeId
* @param cardParam 银行卡参数
* @return
* @throws StripeException
*/
public String updateStripeCustomWithCard(String stripeMemberId, Map<String, Object> cardParam) throws StripeException {
Stripe.apiKey = key;
//创建银行卡Token,顺便借用stripe内部验证校验银行卡信息是否正确
String cardTokenId = createCardToken(cardParam);
Map<String, Object> retrieveParams = new HashMap<>();
List<String> expandList = new ArrayList<>();
expandList.add("sources");
retrieveParams.put("expand", expandList);
Customer customer = Customer.retrieve(stripeMemberId, retrieveParams,null);
Map<String, Object> params = new HashMap<>();
params.put("source", cardTokenId);
Card card = (Card) customer.getSources().create(params);
return card.getId();
}
/**
* 修改默认支付银行卡
* @param stripeMemberId 客户stripeId
* @param stripeCardId 银行卡stripeId
* @throws StripeException
*/
public void updateStripeDefaultCard(String stripeMemberId, String stripeCardId) throws StripeException {
Stripe.apiKey = key;
Map<String, Object> retrieveParams = new HashMap<>();
List<String> expandList = new ArrayList<>();
expandList.add("sources");
retrieveParams.put("expand", expandList);
Customer customer = Customer.retrieve(stripeMemberId, retrieveParams,null);
Map<String, Object> params = new HashMap<>();
params.put("default_source", stripeCardId);
customer.update(params);
}
/**
* 删除用户绑定银行卡
* @param stripeMemberId 客户stripeId
* @param cardId 银行卡stripeId
* @return
* @throws StripeException
*/
public void deleteCard(String stripeMemberId, String cardId) throws StripeException {
Stripe.apiKey = key;
Map<String, Object> retrieveParams = new HashMap<>();
List<String> expandList = new ArrayList<>();
expandList.add("sources");
retrieveParams.put("expand", expandList);
Customer customer = Customer.retrieve( stripeMemberId, retrieveParams, null );
Card card = (Card) customer.getSources().retrieve(cardId);
Card deletedCard = (Card) card.delete();
}
/**
* 生成卡token(鉴定卡对不对)
* @param cardParam number 卡号 exp_month 有效期月份 exp_year 有效期年份 cvc 安全码
* @return
* @throws StripeException
*/
public String createCardToken(Map<String, Object> cardParam) throws StripeException {
Stripe.apiKey = key;
//生成卡片token
Map<String, Object> params = new HashMap<>();
params.put("card", cardParam);
Token token = Token.create(params);
return token.getId();
}
/**
* 修改银行卡信息
* @param stripeMemberId 客户stripeId
* @param stripeCardId 银行卡stripeId
* @param params 需要修改的参数
* @throws StripeException
*/
public void updateCard(String stripeMemberId, String stripeCardId,Map<String, Object> params) throws StripeException {
Stripe.apiKey = key;
Map<String, Object> retrieveParams = new HashMap<>();
List<String> expandList = new ArrayList<>();
expandList.add("sources");
retrieveParams.put("expand", expandList);
Customer customer = Customer.retrieve(stripeMemberId, retrieveParams,null);
Card card = (Card) customer.getSources().retrieve(stripeCardId);
card.update(params);
}
/**
* 同步支付
* @param stripeMemberId 客户stripeId
* @param money 实际支付金额
* @param moneyType 货币单位
* @param description 订单描述
* @return
* @throws StripeException
*/
public boolean charge(String stripeMemberId, BigDecimal money, String moneyType, String description) throws StripeException {
Stripe.apiKey = key;
//发起支付
Map<String, Object> payParams = new HashMap<>();
//1元=100
payParams.put("amount", money.multiply(new BigDecimal(100)).longValue());
payParams.put("currency", moneyType);
payParams.put("description", description);
payParams.put("customer", stripeMemberId);
payParams.put("capture", true);
Charge charge = Charge.create(payParams);
System.err.println(charge.toString());
//charge 支付是同步通知
if ("succeeded".equals(charge.getStatus())) {
//交易成功后,需要更新我们的订单表,修改业务参数,此处省略
return true;
} else {
return false;
}
}
/**
* 捕获stripe平台返回的错误状态码
* @param code
*/
public void catchError(String code){
switch (code){
case "account_number_invalid":
//银行卡号不正确
throw new RRException(null, ErrorPromptEnum.BANK_STRIPE_account_number_invalid.getValue());
case "balance_insufficient":
//账户余额不足
throw new RRException(null, ErrorPromptEnum.BANK_STRIPE_balance_insufficient.getValue());
case "bank_account_declined":
//所提供的银行帐户尚未通过验证或不受支持,因此无法用于收费
throw new RRException(null, ErrorPromptEnum.BANK_STRIPE_bank_account_declined.getValue());
case "bank_account_exists":
//账户已存在
throw new RRException(null, ErrorPromptEnum.BANK_STRIPE_bank_account_exists.getValue());
case "bank_account_unusable":
//提供的银行帐户不能用于付款。必须使用其他银行帐户。
throw new RRException(null, ErrorPromptEnum.BANK_STRIPE_bank_account_unusable.getValue());
case "expired_card":
//卡已过期
throw new RRException(null, ErrorPromptEnum.BANK_STRIPE_expired_card.getValue());
case "incorrect_cvc":
//卡的安全码不正确
throw new RRException(null, ErrorPromptEnum.BANK_STRIPE_incorrect_cvc.getValue());
case "incorrect_number":
//卡号不正确
throw new RRException(null, ErrorPromptEnum.BANK_STRIPE_incorrect_number.getValue());
case "incorrect_zip":
//卡的邮政编码不正确
throw new RRException(null, ErrorPromptEnum.BANK_STRIPE_incorrect_zip.getValue());
case "instant_payouts_unsupported":
//此卡不支持即时付款
throw new RRException(null, ErrorPromptEnum.BANK_STRIPE_instant_payouts_unsupported.getValue());
case "invalid_cvc":
//卡的安全码无效
throw new RRException(null, ErrorPromptEnum.BANK_STRIPE_invalid_cvc.getValue());
case "invalid_expiry_month":
//卡的有效期限不正确
throw new RRException(null, ErrorPromptEnum.BANK_STRIPE_invalid_expiry_month.getValue());
case "invalid_expiry_year":
//卡的有效期不正确
throw new RRException(null, ErrorPromptEnum.BANK_STRIPE_invalid_expiry_year.getValue());
case "invalid_number":
//卡号无效
throw new RRException(null, ErrorPromptEnum.BANK_STRIPE_invalid_number.getValue());
default:
//系统异常
throw new RRException(code, ErrorPromptEnum.BANK_STRIPE_error.getValue());
}
}
}
结尾
以上就是对stripeApi的一个初步探索,不是很全面,很多功能都没用到,要彻底摸透这个支付,任重而道远~~~